@nodefony/frontend 10.0.0-alpha.1

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

@@ -0,0 +1,230 @@
+import { Service, Module } from "nodefony";
+import type { IFrontendService, IFrontendBuildResult } from "../interfaces/IFrontendService.js";
+import type { IFrontendModuleDeclaration, IResolvedFrontendEntry } from "../interfaces/IFrontBuilder.js";
+import type { IViteSupervisorStatus } from "../interfaces/IViteSupervisor.js";
+/**
+ * Service injectable du module `@nodefony/frontend`.
+ *
+ * Cycle de vie :
+ *  1. construction : merge options par défaut + surcharge app (`module-frontend`).
+ *  2. `onKernelReady` : si dev + `autoStartInDevelopment` → start superviseur.
+ *  3. modules consommateurs appellent `registerEntry(...)` dans leur init.
+ *  4. terminate kernel : `stop()` superviseur.
+ *
+ * Branche POC `poc/frontend-child` : utilise `ViteProcessSupervisor` (spawn).
+ * Branche POC `poc/frontend-single` : remplacera par `ViteInProcSupervisor`.
+ */
+declare class FrontendService extends Service implements IFrontendService {
+    #private;
+    module: Module;
+    private readonly cfg;
+    private readonly builder;
+    private readonly entries;
+    /** Une instance Vite par famille d'isolation (`default`, `angular`, …). */
+    private readonly supervisors;
+    /** Template helper par famille (route les `<script>` vers le bon port Vite). */
+    private readonly templateHelpers;
+    /** Index inverse `entryName → famille`, pour router `renderTags`. */
+    private readonly entryFamily;
+    /** Helper prod unique (lit les manifests) — `null` tant qu'on n'est pas en prod. */
+    private prodHelper;
+    /**
+     * L'origine publique est-elle ÉPINGLÉE par une décision explicite
+     * (`frontend.publicOrigin` en config, ou plateforme de dev déporté détectée) ?
+     * `true` → la dérivation par `Host` est désactivée : un réglage voulu gagne
+     * toujours sur une déduction (cf ordre de priorité, README du module).
+     */
+    private originPinned;
+    /**
+     * Ports que l'instance Vite de chaque famille PEUT prendre pour ce démarrage
+     * (bloc de la famille, port-retry compris) — `null` tant que `startDev` n'a
+     * pas établi le plan, et remis à `null` par `stopDev`.
+     *
+     * Alloué une fois par démarrage de développement, jamais en production
+     * (`startDev` n'y tourne pas) : aucun coût par requête.
+     */
+    private plannedPortBlocks;
+    constructor(module: Module);
+    /** Base CDN normalisée (sans slash final). `""` = origine Nodefony. */
+    private get assetBase();
+    /**
+     * Résout l'URL publique d'un asset. Préfixe `p` par `assetBaseUrl` (CDN) si
+     * renseigné, sinon le renvoie tel quel (origine, chemin relatif). Les URLs
+     * absolues (`http(s)://…`) sont renvoyées inchangées. Helper template :
+     * `asset('/test/logo.png')` → `https://cdn.example.com/test/logo.png` ou
+     * `/test/logo.png` (assetBaseUrl vide).
+     */
+    assetUrl(p: string): string;
+    init(): Promise<this>;
+    /**
+     * Enregistre une déclaration frontend d'un module consommateur.
+     *
+     * À appeler dans le `initialize()` ou `onKernelReady()` du module
+     * consommateur — toujours AVANT `onReady` du kernel (sinon le supervisor
+     * démarre sans cette entrée).
+     */
+    registerEntry(consumerModule: Module, declaration: IFrontendModuleDeclaration): IResolvedFrontendEntry;
+    listEntries(): ReadonlyArray<IResolvedFrontendEntry>;
+    status(): IViteSupervisorStatus;
+    statusAll(): ReadonlyArray<{
+        family: string;
+        status: IViteSupervisorStatus;
+    }>;
+    /**
+     * Démarre une instance Vite **par famille d'isolation** (multi-supervisor).
+     *
+     * Résilience : chaque famille démarre indépendamment (`Promise.allSettled`).
+     * Une famille qui échoue (ex. Angular) est isolée — elle ne fait jamais
+     * échouer les autres ni le backend. `startDev` ne rejette que si **aucune**
+     * famille n'a pu démarrer.
+     */
+    startDev(): Promise<void>;
+    /**
+     * Port backend que Vite doit proxifier — le port RÉELLEMENT écouté, pas celui
+     * qu'on espérait.
+     *
+     * `config.backendPort` (5151) n'est qu'une intention : avec
+     * `servers.portPolicy: "auto"`, un port occupé fait glisser l'écoute du backend
+     * (5151 → 5153). Un proxy figé sur 5151 enverrait alors les appels API du front
+     * vers le serveur d'une AUTRE app — au mieux des 404, au pire les données du
+     * voisin. On lit donc le port sur le serveur lui-même.
+     *
+     * Résolution par NOM (`server-http`), jamais par import : `@nodefony/frontend`
+     * ne dépend pas de `@nodefony/http` (cycle via la config d'app).
+     */
+    private resolveBackendPort;
+    /**
+     * Résout les certificats HTTPS partagés (service `certificates` de
+     * @nodefony/http) si `https: true`. Pas de duplication — mêmes PEM que
+     * `server-https` (5152). Retombe sur HTTP avec un warning si indisponible.
+     */
+    private resolveHttps;
+    /**
+     * Template d'origine publique Vite (P14.17). Priorité : `frontend.publicOrigin`
+     * (config, validée — invalide = ERROR + ignorée, jamais un boot cassé) puis
+     * détection de plateforme (Codespaces/Gitpod — variables documentées de la
+     * plateforme, qu'on lit sans les posséder). `undefined` = dérivation locale.
+     * Chaque adaptation est JOURNALISÉE : on doit pouvoir lire dans le boot
+     * pourquoi les `<script>` pointent où ils pointent.
+     */
+    private resolvePublicOriginTemplate;
+    /**
+     * `server.allowedHosts` pour Vite. Vite accepte d'office IP et `localhost` ;
+     * cette liste ne porte que les NOMS. Source des noms légitimes = la MÊME que
+     * la barrière Host de Nodefony (`kernel.domain` + `trustedHosts` http) — une
+     * seule liste à maintenir : autoriser un hôte dans `trustedHosts` ouvre à la
+     * fois la barrière 421 ET Vite. S'y ajoute l'hôte du template d'origine
+     * publique. `trustedHosts: true` (barrière déléguée au reverse-proxy) →
+     * `true` (même délégation). Un pattern non exprimable chez Vite est ANNONCÉ.
+     */
+    private viteAllowedHosts;
+    /** Regroupe les entries par famille d'isolation + remplit l'index inverse. */
+    private groupEntriesByFamily;
+    /**
+     * Démarre l'instance Vite d'une famille sur un port dédié. Enregistre le
+     * supervisor + son template helper AVANT le `start()` (l'état dégradé reste
+     * observable même si le démarrage échoue → rendu propre, pas d'exception).
+     */
+    private startFamily;
+    /**
+     * Câblage prod (idempotent) : monte chaque `outDir` sur son `publicPath`
+     * auprès du serveur statique `server-static` (résolu par nom — pas d'import
+     * http) et crée le helper prod (lecture manifests). No-op si pas d'entrée.
+     *
+     * Une entrée SANS build servirait une page blanche : jamais en silence.
+     * Cas nominal cloud-native : le build est fait à l'image (`npm run build`,
+     * qui chaîne `frontend:build` dans les apps générées) → manifest présent,
+     * zéro travail ici. Cas « prod essayée sur le poste » (devDeps installées →
+     * vite résolvable) : build one-shot au boot — idempotent, et il supprime
+     * l'écran blanc qui perd l'utilisateur, surtout en `--detach`. Sans vite
+     * (image runtime sans devDependencies) : impossible de réparer ici → on
+     * NOMME l'entrée, le manifest attendu et le geste, en ERROR.
+     * Cf project_resilience_no_silent_degradation (fail-soft dispo, fail-loud
+     * dégradation — tout fallback annoncé).
+     */
+    private setupProd;
+    stopDev(): Promise<void>;
+    /**
+     * Build production — `vite.build()` **par entry** (chaque bundle a son propre
+     * `root`/`outDir`/`base`/`manifest` : multi-module + isolation Angular).
+     *
+     * Idempotent : une entrée dont le `manifest.json` est plus récent que ses
+     * sources est **ignorée** (`skipped`) — relance prod console rapide. `force`
+     * rebuild tout. Les échecs sont **collectés** (un bundle KO n'arrête pas les
+     * autres) et remontés dans `failures` → la commande CLI casse l'exit code.
+     *
+     * ⚠️ **`NODE_ENV` est posé le temps du build, et restauré.** Vite dérive son
+     * `isProduction` de `process.env.NODE_ENV`, qui **prime sur le `mode`** de la
+     * configuration : une commande CLI, dont le kernel démarre en développement,
+     * produisait donc un bundle de DÉVELOPPEMENT malgré `mode: "production"` —
+     * `import.meta.env.DEV` vrai chez l'utilisateur final (tout code gardé par ce
+     * drapeau s'exécutait en production), et les messages d'aide de Vue publiés.
+     * La restauration n'est pas une précaution de style : `build()` est aussi
+     * appelé par `setupProd()`, et laisser la variable retournée marquerait un
+     * process de développement comme production pour le reste de sa vie.
+     *
+     * @param opts.force ignore le cache de fraîcheur (rebuild systématique).
+     */
+    build(opts?: {
+        force?: boolean;
+    }): Promise<IFrontendBuildResult>;
+    /**
+     * Une entrée est « fraîche » si son `manifest.json` existe ET qu'aucun fichier
+     * source (sous `root`, hors `node_modules`/`outDir`/`.vite`) n'est plus récent.
+     * Scan disque borné (dossier front petit) — évite un rebuild Vite inutile.
+     */
+    private isBuildFresh;
+    /** Mtime du fichier le plus récent sous `dir` (récursif borné). */
+    private newestSourceMtime;
+    /**
+     * Document HTML complet pour une entrée — lit l'`index.html` du module
+     * (le dev y met meta/polices/scripts externes) + injecte les tags Nodefony.
+     * Le controller renvoie : `this.render(svc.renderDocument("x", this.context.cspNonce))`.
+     * @param nonce nonce CSP de la requête (`Context.cspNonce`) — propagé aux `<script>`.
+     */
+    renderDocument(entryName: string, nonce?: string, requestHost?: string): string;
+    renderTags(entryName: string, nonce?: string, requestHost?: string): string;
+    /**
+     * Le `Host` de la requête peut-il servir à dériver l'origine des assets ?
+     *
+     * Trois conditions, dans cet ordre — chacune protège un cas RÉEL :
+     *  1. **origine non épinglée** : un `frontend.publicOrigin` explicite (ou une
+     *     plateforme de dev déporté détectée) est une décision de l'auteur, elle
+     *     gagne toujours sur une déduction ;
+     *  2. **barrière `trustedHosts` franchie** : le `Host` est une donnée
+     *     CLIENTE. Sans ce filtre, un `Host` forgé ferait émettre des
+     *     `<script src="https://attaquant:5173/…">` dans une page de dev ;
+     *  3. **barrière non déléguée** (`trustedHosts !== true`) : le bypass total
+     *     ne dit plus rien de la légitimité d'un nom, et surtout le CSP émis par
+     *     le firewall (`#viteCspFragment`) ne couvre alors QUE loopback +
+     *     domaine canonique — dériver ailleurs produirait une page dont les
+     *     scripts sont bloqués. Les deux listes doivent rester la même liste.
+     *
+     * @returns le nom d'hôte à employer, ou `undefined` pour garder l'origine
+     *   résolue au démarrage (comportement d'avant la dérivation).
+     */
+    private derivableHost;
+    /**
+     * Ports Vite à déclarer au CSP, famille par famille : le BLOC entier tant que
+     * l'instance ne sert pas, son port RÉEL dès qu'elle sert.
+     *
+     * Pourquoi le bloc avant : le CSP part AVEC la page et ne se renégocie jamais.
+     * Une page servie avant que Vite ait résolu son port doit déjà porter le port
+     * qu'il prendra, sinon son socket de rechargement à chaud est refusé pour
+     * toute la durée de la page.
+     *
+     * Pourquoi le port seul après : la plage est le prix d'une incertitude, elle
+     * ne doit pas lui survivre. Mesuré sur ce dépôt (3 familles × 4 hôtes de
+     * confiance), garder les blocs porte l'en-tête CSP à ~7,9 Ko sur CHAQUE
+     * réponse, contre ~2,3 Ko une fois les ports connus — au bord des 8 Ko que
+     * refusent beaucoup de relais.
+     *
+     * Développement seulement : `startDev` ne tourne pas en production. La
+     * garantie reste une liste d'origines nommées — jamais un `ws:` sans hôte,
+     * qui la supprimerait au lieu de corriger le symptôme.
+     *
+     * @returns ports en chaîne, dédupliqués ; repli `devPort` si rien n'est connu.
+     */
+    private cspPorts;
+}
+export default FrontendService;

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

@@ -0,0 +1,66 @@
+import type { IResolvedFrontendEntry } from "../interfaces/IFrontBuilder.js";
+/**
+ * Génère le contenu d'un `vite.config.generated.mjs` pour le superviseur
+ * child_process. Le fichier généré est autosuffisant : il importe Vite +
+ * les plugins de chaque preset hardcodés selon les types détectés.
+ *
+ * Pourquoi pas appeler `IFrontBuilder.buildViteConfig()` directement et
+ * passer la config en stdin ? Parce que Vite ne lit pas la config depuis
+ * stdin, et que les plugins (instances JS) ne sont pas sérialisables JSON.
+ */
+export interface ViteConfigGeneratorOptions {
+    /**
+     * Origine du serveur Nodefony pour le proxy Vite (`server.proxy`).
+     * Exemple : `"http://127.0.0.1:5151"`. En dev uniquement — ignoré en prod.
+     */
+    readonly backendOrigin?: string;
+    /**
+     * Origine publique du dev server Vite — ex `"http://127.0.0.1:5173"`.
+     * Définie comme `base` dans Vite, ce qui force les imports internes du
+     * source transformé (ex `/src/App.tsx`) à devenir absolus
+     * (`http://host:port/src/App.tsx`). Sans ça, une page rendue par
+     * Nodefony (5151) qui charge `/src/main.tsx` voit ses imports résolus
+     * contre 5151 → 404. Active aussi `strictPort` pour garantir l'origine.
+     */
+    readonly viteOrigin?: string;
+    /**
+     * Certificats HTTPS — paths absolus vers les fichiers PEM. Quand fourni,
+     * la config Vite générée inclut `server.https: { key, cert }` (lus via
+     * `fs.readFileSync` au démarrage Vite).
+     */
+    readonly https?: {
+        readonly keyPath: string;
+        readonly certPath: string;
+    };
+    /**
+     * Hôtes acceptés dans le header `Host` (`server.allowedHosts`, Vite ≥6).
+     * `true` = tous. Un motif `.suffixe` couvre le domaine et ses sous-domaines.
+     * Les IP et `localhost` sont toujours acceptés par Vite — cette liste ne
+     * sert que les NOMS (vhosts, `host.docker.internal`, forwarders).
+     */
+    readonly allowedHosts?: true | ReadonlyArray<string>;
+    /**
+     * Config `server.hmr` CLIENTE — où le navigateur ouvre le WebSocket HMR
+     * quand un intermédiaire (forwarder TLS, passerelle conteneur) sépare
+     * l'origine publique de l'adresse d'écoute. Absent = fallback client Vite
+     * (`location.hostname` + port d'écoute), correct en local.
+     */
+    readonly hmr?: {
+        readonly host: string;
+        readonly clientPort: number;
+        readonly protocol: "ws" | "wss";
+    };
+}
+export declare class ViteConfigGenerator {
+    /**
+     * Construit le content `.mjs` à écrire à côté de `index.html` du module.
+     *
+     * Si `opts.backendOrigin` est fourni en mode `development`, agrège les
+     * `apiProxyPaths` de toutes les entries et génère un `server.proxy` qui
+     * forward chaque préfixe vers le backend Nodefony. Sans ça, les fetch
+     * relatifs depuis l'app servie par Vite atterrissent sur Vite et reçoivent
+     * un SPA-fallback HTML (cause classique de `Unexpected token '<'`).
+     */
+    toMjs(entries: ReadonlyArray<IResolvedFrontendEntry>, mode: "development" | "production", opts?: ViteConfigGeneratorOptions): string;
+}
+export default ViteConfigGenerator;

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

@@ -0,0 +1,214 @@
+import type { IViteSupervisor, IViteSupervisorStatus } from "../interfaces/IViteSupervisor.js";
+import type { IResolvedFrontendEntry } from "../interfaces/IFrontBuilder.js";
+/**
+ * Logger minimal — injecté par FrontendService pour piper les logs Vite
+ * dans le syslog Nodefony sans dépendance dure sur Service.
+ */
+export interface IViteSupervisorLogger {
+    info(msg: string): void;
+    error(msg: string): void;
+    debug?(msg: string): void;
+}
+export interface ViteSupervisorOptions {
+    readonly devHost: string;
+    readonly devPort: number;
+    /**
+     * Template d'origine PUBLIQUE du dev server (P14.17) — `{port}` substitué au
+     * port RÉEL de chaque spawn (suit les retries de port). Vide/absent = dérivé
+     * de `devHost:port`. Dissocie ce que Vite ÉCOUTE de ce que le navigateur
+     * APPELLE (forwarder Codespaces/Gitpod, `host.docker.internal`, remap).
+     */
+    readonly publicOriginTemplate?: string;
+    /**
+     * Hôtes que Vite doit accepter dans le header `Host` (`server.allowedHosts`).
+     * `true` = tous. Dérivé par FrontendService de la liste `trustedHosts` http —
+     * jamais maintenu ici (1 règle = 1 implémentation).
+     */
+    readonly allowedHosts?: true | ReadonlyArray<string>;
+    readonly startupTimeoutMs: number;
+    readonly pipeLogs: boolean;
+    readonly cwd: string;
+    readonly logger: IViteSupervisorLogger;
+    /**
+     * Origine du serveur Nodefony pour `server.proxy` côté Vite — ex `"http://127.0.0.1:5151"`.
+     * Quand fourni, les paths `apiProxyPaths` des entries sont proxifiés vers ce backend.
+     */
+    readonly backendOrigin?: string;
+    /**
+     * Certificats à utiliser si Vite doit servir en HTTPS. Paths absolus vers les
+     * fichiers PEM — les mêmes que Nodefony utilise pour son `server-https` (5152).
+     */
+    readonly https?: {
+        readonly keyPath: string;
+        readonly certPath: string;
+    };
+    /** Valeur de `NODE_ENV` à propager au child Vite — généralement `kernel.environment`. */
+    readonly nodeEnv?: string;
+    /**
+     * Variables d'env additionnelles passées au child Vite. Les clés `VITE_*`
+     * sont automatiquement exposées au browser via `import.meta.env`.
+     */
+    readonly extraEnv?: Record<string, string>;
+    /** Auto-restart sur crash inattendu de Vite (default `true`). */
+    readonly autoRestart?: boolean;
+    /** Max tentatives de restart avant d'abandonner (default `5`). */
+    readonly maxRestarts?: number;
+    /** Délai initial du backoff exponentiel — doublé à chaque tentative (default `500ms`). */
+    readonly restartBackoffBaseMs?: number;
+    /** Plafond du backoff (default `8000ms` = 8s). */
+    readonly restartBackoffMaxMs?: number;
+    /**
+     * Intervalle health check (default `30000` = 30s). `0` désactive.
+     * Le supervisor fait un GET HTTP(S) sur `viteOrigin/` et compte les échecs
+     * consécutifs ; au-delà du seuil, kill le child → trigger auto-restart.
+     */
+    readonly healthCheckIntervalMs?: number;
+    /** Échecs health check consécutifs avant restart (default `3`). */
+    readonly healthCheckFailureThreshold?: number;
+    /** Timeout d'un health check individuel (default `5000ms`). */
+    readonly healthCheckTimeoutMs?: number;
+    /**
+     * Tentatives de port à essayer si EADDRINUSE (default `3`).
+     * Le supervisor essaie devPort, devPort+1, devPort+2.
+     */
+    readonly portRetryAttempts?: number;
+}
+/**
+ * Un texte (message d'erreur OU sortie brute de Vite) dénonce-t-il un port occupé ?
+ *
+ * **Source UNIQUE** de cette décision. Elle était dupliquée en deux regex qui ont
+ * divergé : l'une cherchait `port X is in use`, alors que Vite écrit
+ * `Port 5173 is ALREADY in use`. Résultat, le retry de port ne se déclenchait
+ * jamais et la seconde app perdait tout son frontend — un conflit de port pourtant
+ * parfaitement rattrapable. On tolère donc les deux formulations, et on ne
+ * l'écrit qu'ici (deux implémentations d'une même règle = dérive garantie).
+ */
+export declare function isPortInUseMessage(text: string): boolean;
+/**
+ * Message d'échec d'un boot qui n'a jamais rendu la main dans le temps imparti —
+ * en y REPORTANT ce que vite avait déjà dit.
+ *
+ * Le conflit de port ne se voit que dans la sortie du child. Le rejet par
+ * échéance ne portait que la durée : un boot qui annonçait « Port 5173 is
+ * already in use » puis restait pendu (vite ne meurt pas toujours, et sur une
+ * application réelle le pré-bundling tient l'échéance) sortait sous le libellé
+ * `timeout after …`, que le détecteur de port occupé ne reconnaît pas. Le repli
+ * sur `port+1` existait et n'était jamais atteint — la sortie d'échec choisie
+ * décidait à elle seule si la 2ᵉ application aurait un frontend.
+ *
+ * Fonction PURE : la règle « ce qu'on a OBSERVÉ prime sur la façon dont on a
+ * échoué » se teste sans spawn, donc sans dépendre d'une course entre l'écriture
+ * de l'erreur et la mort du process.
+ *
+ * @param timeoutMs - échéance dépassée.
+ * @param observed - sortie brute accumulée du child (stdout + stderr).
+ * @returns message d'erreur, préfixé `EADDRINUSE:` si un port occupé est dénoncé.
+ */
+export declare function startupTimeoutMessage(timeoutMs: number, observed: string): string;
+/**
+ * Superviseur Vite résilient — branche POC `poc/frontend-child`.
+ *
+ * Garanties :
+ *  - Idempotent : appels concurrents à `start()` partagent la même promesse.
+ *  - Auto-restart : crash inattendu → restart avec backoff exponentiel borné.
+ *  - Port conflict : retry sur port+1 jusqu'au plafond `portRetryAttempts`.
+ *  - Health check : ping périodique, kill+restart sur N échecs consécutifs.
+ *  - Cleanup strict : listeners + timers tracés et libérés au `stop()`.
+ *
+ * Tous les listeners sur `child` sont supprimés explicitement avant qu'on
+ * laisse le child mourir (évite memory leak entre restarts).
+ */
+export declare class ViteProcessSupervisor implements IViteSupervisor {
+    private readonly opts;
+    private readonly cfg;
+    private readonly generator;
+    private child;
+    private state;
+    private resolvedPort;
+    /** Origine publique du spawn courant (source unique des URLs — cf status). */
+    private resolvedOrigin;
+    private lastError;
+    private entries;
+    private configFilePath;
+    private restartCount;
+    private healthFailures;
+    private healthCheckTimer;
+    private restartTimer;
+    private startPromise;
+    private stopPromise;
+    private willingShutdown;
+    /** Kill VOULU par le health check (recovery) : le prochain exit doit relancer. */
+    private expectRestartKill;
+    /**
+     * Signal d'arrêt reçu par NOTRE process (Ctrl+C au groupe foreground, SIGTERM
+     * d'un orchestrateur) → tout exit de Vite est un ARRÊT, jamais un crash.
+     * Indispensable : Vite intercepte SIGINT et sort `code=130, signal=null` —
+     * indiscernable d'un crash côté exit event, et `willingShutdown` (posé par le
+     * stop du kernel) arrive APRÈS la mort de Vite (race sans IPC, vécu Ctrl+C :
+     * « vite restart #1 failed » en ERROR sur un arrêt normal).
+     */
+    private readonly markShutdown;
+    /**
+     * Listeners attachés au child courant — drainés à chaque mort du child.
+     * Sans ça, le child gardé en référence (avant GC) accumule des handlers
+     * entre restarts → MaxListenersExceededWarning + leak.
+     */
+    private childListeners;
+    constructor(opts: ViteSupervisorOptions);
+    start(entries: ReadonlyArray<IResolvedFrontendEntry>, _viteConfigUnused: Record<string, unknown>): Promise<void>;
+    stop(): Promise<void>;
+    status(): IViteSupervisorStatus;
+    /**
+     * Essaie de spawn Vite en variant le port si EADDRINUSE. Le port résolu
+     * est stocké dans `resolvedPort` (utilisé par status() + TemplateHelper).
+     */
+    private spawnWithPortRetry;
+    /** Replis de port du DERNIER démarrage — cf `IViteSupervisorStatus.portRetries`. */
+    private portRetries;
+    private isPortInUseError;
+    /** Spawn Vite sur un port donné et attend le ready. */
+    private attemptSpawn;
+    private waitReady;
+    /**
+     * Après que Vite est ready, on attache un handler qui distingue :
+     *  - shutdown volontaire (willingShutdown=true → state=stopped, no restart)
+     *  - crash inattendu (state=ready au moment du exit → scheduleRestart)
+     */
+    private attachRuntimeExitHandler;
+    private scheduleRestart;
+    private startHealthCheck;
+    private stopHealthCheck;
+    /**
+     * Ping HTTP(S) GET sur la racine de Vite. Considère réussi si réception de
+     * headers (même 4xx — Vite ne renvoie pas forcément 200 à `/`).
+     */
+    private pingVite;
+    /** Stop volontaire — n'enclenche PAS l'auto-restart. */
+    private doStop;
+    /** Force kill du child (pour les health checks failing). Le exit handler gère le restart. */
+    private killChild;
+    /**
+     * Envoie un signal à l'ARBRE de Vite — lui et ses propres enfants, à commencer par
+     * le service esbuild que Vite lance pour la pré-optimisation des dépendances.
+     *
+     * `child.kill()` n'atteint que Vite. Sous POSIX cela suffit en pratique : Vite n'est
+     * pas leader de son groupe (`detached: false`, voulu — un Ctrl+C terminal doit
+     * l'atteindre), donc le comportement ici est inchangé, et l'arbre est de toute façon
+     * emporté par le groupe du superviseur de développement. Sous Windows il n'y a pas de
+     * groupe du tout : les descendants survivaient à chaque arrêt, et `stopDev()` laissait
+     * un service esbuild derrière lui.
+     *
+     * Une seule implémentation dans le dépôt ({@link signalProcessGroup}, cœur) : groupe
+     * POSIX ou `taskkill /T` selon la plateforme. La recopier ici aurait fait réapparaître
+     * l'angle mort qu'on venait de fermer dans le superviseur de développement.
+     *
+     * @returns ce qui a pu être atteint. `gone` = plus rien à tuer, donc plus aucun `exit`
+     *   à attendre : c'est un VERDICT, là où l'arrêt reposait jusqu'ici sur une exception
+     *   remontée par `child.kill()`. Une exception dit qu'un appel a échoué, pas ce qu'il
+     *   est advenu du process — et elle disparaît dès qu'un intermédiaire la rattrape.
+     */
+    private signalTree;
+    private trackListener;
+    private cleanupChildListeners;
+}
+export default ViteProcessSupervisor;

package/dist/types/nodefony/src/FrontendAdminApi.d.ts

@@ -0,0 +1,63 @@
+import type { IAdminApi } from "nodefony";
+import type FrontendService from "../service/FrontendService.js";
+/**
+ * Producteur `IAdminApi` du builder frontend — exposé sous `/nodefony/frontend/api/*`.
+ * Surface l'état du **superviseur Vite** (dev) pour la visibilité Studio : process Vite
+ * (pid), port réel résolu, état (donc HMR actif), bundles servis.
+ *
+ * Vite est un outil **DEV-only** : en production le superviseur ne tourne pas (état
+ * `idle`, pid `null`) — l'UI vient alors du bundle compilé (`manifest.json`). L'endpoint
+ * répond dans les deux cas (best-effort, jamais throw) : le front en déduit l'affichage.
+ */
+/** Vue SÛRE d'une instance Vite — sans chemins FS absolus (anti info-leak). */
+export interface IViteInstanceView {
+    /** Famille d'isolation (`default`, `angular`, …). */
+    family: string;
+    /** État du superviseur (`ready` = HMR actif). */
+    state: string;
+    /** Hôte d'ÉCOUTE du serveur Vite (dev). */
+    host: string;
+    /** Origine PUBLIQUE effective (celle que le navigateur utilise) — `null` si non démarré. */
+    origin: string | null;
+    /** Port RÉEL résolu (Vite incrémente si occupé) — `null` si non démarré. */
+    port: number | null;
+    /** PID du process enfant Vite — `null` hors dev. */
+    pid: number | null;
+    /** Vite servi en HTTPS (suit la config du serveur). */
+    https: boolean;
+    /** Redémarrages du superviseur depuis le boot. */
+    restartCount: number;
+    /** Échecs de health-check du superviseur. */
+    healthFailures: number;
+    /** Entrées servies — nom logique + type + version du framework UI. */
+    entries: {
+        entryName: string;
+        type: string;
+        version?: string;
+    }[];
+}
+/** Snapshot frontend servi par l'endpoint `vite`. */
+export interface IFrontendStatusView {
+    /** Au moins une instance Vite `ready` (HMR actif). */
+    available: boolean;
+    /** Version de Vite (le builder), si résolue. */
+    vite?: string;
+    /** Instance principale (famille `default` ou la première). */
+    primary: IViteInstanceView;
+    /** Toutes les instances (multi-bundle). */
+    bundles: IViteInstanceView[];
+}
+/**
+ * Construit le snapshot frontend (état Vite) — lecture pure, jamais throw.
+ *
+ * @param service - le {@link FrontendService} (résolu du container).
+ * @returns la vue sûre prête à `renderJson` / push realtime.
+ */
+export declare function buildFrontendStatus(service: FrontendService): IFrontendStatusView;
+/**
+ * Construit le producteur `IAdminApi` du frontend (namespace `"frontend"`).
+ *
+ * @param service - le {@link FrontendService} à introspecter.
+ * @returns le contrat admin, prêt à `broker.register()`.
+ */
+export declare function createFrontendAdminApi(service: FrontendService): IAdminApi;

package/dist/types/nodefony/src/builders/ViteBuilder.d.ts

@@ -0,0 +1,17 @@
+import type { IFrontBuilder, IResolvedFrontendEntry } from "../../interfaces/IFrontBuilder.js";
+import type { IFrontPreset } from "../../interfaces/IFrontPreset.js";
+/**
+ * Construit la config Vite finale à partir des entrées résolues et des presets.
+ *
+ * Le builder ne lance JAMAIS Vite — il fournit uniquement la config. Le
+ * démarrage est délégué au superviseur (child_process ou in-proc).
+ */
+export declare class ViteBuilder implements IFrontBuilder {
+    private readonly presets;
+    constructor();
+    listPresets(): ReadonlyArray<IFrontPreset>;
+    getPreset(type: IFrontPreset["type"]): IFrontPreset | undefined;
+    registerPreset(preset: IFrontPreset): void;
+    buildViteConfig(entries: ReadonlyArray<IResolvedFrontendEntry>, mode: "development" | "production", assetBaseUrl?: string): Promise<Record<string, unknown>>;
+}
+export default ViteBuilder;

package/dist/types/nodefony/src/errors/FrontendError.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Erreur de base pour @nodefony/frontend.
+ *
+ * - `code` : identifiant machine, consommé par Vision et l'audit-logger.
+ * - `context` : payload structuré pour le PDU syslog.
+ */
+export declare class FrontendError extends Error {
+    readonly code: string;
+    readonly context?: Record<string, unknown> | undefined;
+    constructor(message: string, code: string, context?: Record<string, unknown> | undefined);
+}
+/** Preset inconnu — module a déclaré `type: "foo"` non enregistré. */
+export declare class FrontendPresetUnknownError extends FrontendError {
+    constructor(type: string);
+}
+/** Echec de démarrage de Vite (spawn raté, port occupé, config invalide). */
+export declare class FrontendSupervisorStartError extends FrontendError {
+    constructor(reason: string, cause?: unknown);
+}
+/** Au moins un bundle a échoué au build production (Vite). */
+export declare class FrontendBuildError extends FrontendError {
+    readonly failures: ReadonlyArray<{
+        entryName: string;
+        message: string;
+    }>;
+    constructor(failures: ReadonlyArray<{
+        entryName: string;
+        message: string;
+    }>);
+}
+/** Aucune entrée front trouvée alors qu'on tente de démarrer le dev server. */
+export declare class FrontendNoEntriesError extends FrontendError {
+    constructor();
+}