@nodefony/frontend 10.0.0-alpha.1

package/README.md

@@ -0,0 +1,338 @@
+# @nodefony/frontend
+
+Builder frontend Nodefony — supervise [Vite](https://vite.dev/) dans un process séparé pour transpiler les frontends de tes modules (React 19, Vue 3, Angular, vanilla TS).
+
+> Audience : développeur Nodefony qui ajoute son **premier frontend** à un module existant. Tu connais déjà `Module`, `Service`, `Controller`. Si non, lis d'abord le [CLAUDE.md racine](https://github.com/nodefony/nodefony-core/blob/claude-ts/CLAUDE.md).
+
+---
+
+## Pourquoi un process séparé ?
+
+Vite a besoin d'un event-loop et d'un tas V8 pour compiler/HMR. L'exécuter **in-proc** dans le serveur Nodefony bloque les requêtes pendant les rebuilds. Un process séparé (`child_process.spawn`) isole parfaitement Vite du backend :
+
+- Crash Vite ≠ crash Nodefony
+- Compilation Vite ≠ latence event-loop Nodefony
+- HMR WebSocket de Vite reste autonome
+- Auto-restart en cas de mort du child (résilience built-in)
+
+---
+
+## Quickstart — ajouter un frontend à ton module
+
+### 1. Activer `@nodefony/frontend` dans l'app
+
+Dans `index.ts` racine :
+
+```ts
+@modules([
+  "@nodefony/http",
+  "@nodefony/framework",
+  "@nodefony/frontend",       // ← avant ton module consumer
+  "@nodefony/mon-module",
+])
+class App extends Module { ... }
+```
+
+> **Ordre important** : `@nodefony/frontend` doit être déclaré AVANT les modules qui appellent `registerEntry()` — sinon le service `frontend` n'existe pas dans le DI Container au moment du `onKernelBoot()` du consumer.
+
+### 2. Installer les peer deps
+
+```bash
+npm i -D vite @vitejs/plugin-react   # react19 / react-dom
+# ou
+npm i -D vite @vitejs/plugin-vue     # vue3
+```
+
+### 3. Déclarer ton frontend dans le module consumer
+
+```ts
+import { Kernel, Module } from "nodefony";
+import { controllers } from "@nodefony/framework";
+import type { FrontendService } from "@nodefony/frontend";
+import config from "./nodefony/config/config";
+import MyController from "./nodefony/controller/MyController";
+
+@controllers([MyController])
+class MyModule extends Module {
+  constructor(kernel: Kernel) {
+    super("my-module", kernel, import.meta.url, config);
+  }
+
+  override async onKernelBoot(): Promise<this> {
+    const svc = this.kernel?.container?.get("frontend") as
+      FrontendService | undefined;
+    svc?.registerEntry(this, {
+      type: "react19", // | "vanilla"
+      entry: "./frontend/src/main.tsx", // relatif au module
+      root: "./frontend", // contient index.html
+      outDir: "./public/dist", // pour la prod build
+      name: "my-module", // nom logique (entryName)
+      // Quand le browser fait fetch("/my/api/x") depuis l'app Vite,
+      // Vite proxifie vers Nodefony :
+      apiProxyPaths: ["/my/api"],
+    });
+    return this;
+  }
+}
+```
+
+### 4. Créer le frontend Vite
+
+```
+src/modules/my-module/frontend/
+├── index.html                    ← (peut être absent — Nodefony rend la page elle-même)
+├── src/
+│   ├── main.tsx                  ← entry point (React 19 ici)
+│   └── App.tsx
+```
+
+`main.tsx` standard :
+
+```tsx
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+import { App } from "./App";
+
+const rootEl = document.getElementById("root");
+if (!rootEl) throw new Error("#root not found");
+createRoot(rootEl).render(
+  <StrictMode>
+    <App />
+  </StrictMode>,
+);
+```
+
+### 5. Rendre la page depuis un Controller
+
+```ts
+import { Controller, route, controller } from "@nodefony/framework";
+import { Context } from "@nodefony/http";
+import type { FrontendService } from "@nodefony/frontend";
+
+@controller("/my-route")
+class MyController extends Controller {
+  constructor(context: Context) {
+    super("MyController", context);
+  }
+
+  @route("my-react", { path: "/" })
+  renderReact(): unknown {
+    this.setContextHtml();
+    const svc = this.context?.container?.get("frontend") as
+      FrontendService | undefined;
+
+    // Rien à faire pour la CSP : en développement, le service déclare les
+    // origines Vite au firewall (`@nodefony/security`), qui émet UN seul
+    // en-tête. Un controller qui le réécrirait écraserait le nonce.
+
+    // Deux données de la requête sont propagées au rendu :
+    //  - le nonce CSP, sans lequel `script-src 'nonce-…'` bloque les balises ;
+    //  - l'hôte, dont l'origine des assets Vite est dérivée en développement —
+    //    la page annonce l'origine par laquelle le client est arrivé, si bien
+    //    qu'un poste et un navigateur en conteneur sont servis en même temps,
+    //    sans configuration. Scheme et port restent ceux de Vite.
+    const viteTags =
+      svc?.renderTags(
+        "my-module",
+        this.context?.cspNonce,
+        this.context?.domain,
+      ) ?? "<!-- @nodefony/frontend not started -->";
+
+    return this.render(`<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>My App</title>
+    ${viteTags}
+  </head>
+  <body>
+    <div id="root"></div>
+  </body>
+</html>`);
+  }
+}
+```
+
+### 6. Lancer le serveur dev
+
+```bash
+npx nodefony development
+```
+
+Le superviseur Vite démarre automatiquement sur l'event `onServersReady` du kernel (après que les 4 serveurs Nodefony écoutent). Tu verras dans le syslog :
+
+```
+INFO frontend : registered entry: my-module (react19) from "my-module"
+INFO frontend : vite dev server ready on 127.0.0.1:5173
+```
+
+Va sur `http://127.0.0.1:5151/my-route/` — Nodefony rend l'HTML, le browser tape Vite (5173) pour les assets, HMR fonctionne en édition de `App.tsx`.
+
+---
+
+## Config complète
+
+Dans le `config.ts` de **ton app** ou de **ton module** :
+
+```ts
+const config = {
+  "module-frontend": {
+    devHost: "127.0.0.1", // host d'écoute Vite
+    devPort: 5173, // port Vite (incrémenté si occupé)
+    autoStartInDevelopment: true, // démarre Vite en env=development
+    pipeViteLogs: true, // logs Vite dans syslog Nodefony
+
+    // HTTPS — partage les certs Nodefony (server-https 5152)
+    https: true, // false par défaut
+
+    // Proxy backend Vite → Nodefony
+    backendHost: "127.0.0.1",
+    backendPort: 5151,
+    backendProtocol: "http", // http | https
+
+    // Variables d'env passées à Vite (les VITE_* sont exposées au browser)
+    viteEnv: {
+      VITE_API_BASE: "/api/v1",
+    },
+
+    // Résilience supervisor
+    resilience: {
+      autoRestart: true, // restart sur crash
+      maxRestarts: 5, // avant abandon
+      restartBackoffBaseMs: 500, // backoff exponentiel
+      restartBackoffMaxMs: 8_000,
+      healthCheckIntervalMs: 30_000, // ping HTTP périodique (0 = off)
+      healthCheckFailureThreshold: 3, // échecs avant restart
+      portRetryAttempts: 3, // port+1, port+2 sur EADDRINUSE
+    },
+  },
+};
+```
+
+Tout est optionnel — les defaults fonctionnent out-of-the-box.
+
+---
+
+## Events du supervisor
+
+`FrontendService` est un `Service` Nodefony (donc un `EventEmitter`). Tu peux écouter :
+
+| Event               | Payload                      | Quand                                   |
+| ------------------- | ---------------------------- | --------------------------------------- |
+| `frontend:starting` | `{ backendOrigin, entries }` | Juste avant le spawn Vite               |
+| `frontend:ready`    | `IViteSupervisorStatus`      | Vite a annoncé `Local:` dans son stdout |
+| `frontend:error`    | `Error`                      | Spawn ou ready timeout échoué           |
+| `frontend:stopped`  | (rien)                       | Après `stop()` propre (SIGINT envoyé)   |
+
+Exemple :
+
+```ts
+const svc = kernel.container.get("frontend") as FrontendService;
+svc.on("frontend:ready", (status) => {
+  console.log(`Vite up on ${status.host}:${status.port}`);
+});
+```
+
+---
+
+## API publique du service
+
+```ts
+interface IFrontendService {
+  registerEntry(module, declaration): IResolvedFrontendEntry;
+  listEntries(): ReadonlyArray<IResolvedFrontendEntry>;
+  status(): IViteSupervisorStatus;
+  startDev(): Promise<void>; // appelé auto par onServersReady
+  stopDev(): Promise<void>;
+  build(): Promise<void>; // vite.build() in-proc
+  // `nonce` = `Context.cspNonce` ; `requestHost` = `Context.domain` (sans port),
+  // dont l'origine des assets est dérivée en développement.
+  renderTags(entryName, nonce?, requestHost?): string;
+  renderDocument(entryName, nonce?, requestHost?): string;
+  assetUrl(path): string;
+}
+```
+
+---
+
+## Troubleshooting
+
+### Page blanche, scripts bloqués par CSP
+
+Le helmet de `@nodefony/security` pose `script-src 'self'` par défaut. Override dans le controller :
+
+```ts
+this.context.response.setHeader(
+  "Content-Security-Policy",
+  svc.getCspDirectives(),
+);
+```
+
+### `Unexpected token '<'` sur `fetch("/api/...")`
+
+Vite sert son SPA-fallback HTML pour les routes inconnues. Déclare le préfixe dans `apiProxyPaths` :
+
+```ts
+svc.registerEntry(this, { ..., apiProxyPaths: ["/my/api"] });
+```
+
+### `@vitejs/plugin-react can't detect preamble`
+
+Le `TemplateHelper` injecte automatiquement le preamble React Fast Refresh pour les entries `type: "react19"`. Si tu vois cette erreur, vérifie que tu utilises bien `svc.renderTags("entry-name")` au lieu d'injecter les `<script>` à la main.
+
+### Vite démarre sur un autre port que `devPort`
+
+Le port configuré est pris. Le supervisor retry automatiquement sur `port+1`, `port+2` (option `portRetryAttempts`). Vérifie le port résolu via `svc.status().port`.
+
+### Le browser refuse le cert HTTPS de Vite (`https: true`)
+
+Va sur `https://127.0.0.1:5173/` une fois et accepte le certificat. Ou installe la CA root Nodefony : `nodefony/config/certificates/ca/nodefony-root-ca.crt.pem` dans ton trousseau.
+
+### Vite crash en boucle (`max restarts reached`)
+
+Le superviseur abandonne après `maxRestarts` (default 5). Regarde les logs Vite dans le syslog (`[vite!] ...`) pour la cause. Augmente `maxRestarts` ou fix le source du crash.
+
+---
+
+## Tests
+
+```bash
+npm test                     # unit — ViteConfigGenerator
+npm run test:integration     # intégration — supervisor, spawn réel
+```
+
+Les tests d'intégration nécessitent `vite` installé (déjà en devDependencies du repo).
+
+---
+
+## Architecture (résumé)
+
+```
+Module consumer
+   │ onKernelBoot()
+   ↓
+FrontendService.registerEntry()       ← collecte les frontends à transpiler
+   │
+Kernel "onServersReady"               ← 4 servers Nodefony écoutent
+   ↓
+FrontendService.startDev()
+   ↓
+ViteProcessSupervisor.start()
+   ├─ écrit vite.config.generated.mjs (proxy, https, base, env)
+   ├─ spawn("npx", ["vite", "--config", ...])
+   ├─ parse stdout "Local: https://host:port" → state = "ready"
+   ├─ attach exit handler (auto-restart si crash inattendu)
+   └─ start health check loop (ping HTTP périodique)
+
+Browser GET /my-route/
+   │
+Nodefony rend HTML + svc.renderTags() injecte:
+   <script type="module">  preamble React Fast Refresh
+   <script src="https://host:5173/@vite/client">
+   <script src="https://host:5173/src/main.tsx">
+
+Browser → 5173 (Vite) pour les assets + HMR WSS
+Browser → 5173 pour /api/... → Vite proxifie vers Nodefony (5151/5152)
+```
+
+Détails internes (dans le dépôt) : voir [`CLAUDE.md`](https://github.com/nodefony/nodefony-core/blob/claude-ts/src/packages/@nodefony/frontend/CLAUDE.md) et [`MEMORY.md`](https://github.com/nodefony/nodefony-core/blob/claude-ts/src/packages/@nodefony/frontend/MEMORY.md).

package/dist/_virtual/_@oxc-project_runtime@0.148.0/helpers/esm/decorate.js

@@ -0,0 +1,9 @@
+//#region \0@oxc-project+runtime@0.148.0/helpers/esm/decorate.js
+function __decorate(decorators, target, key, desc) {
+	var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+	if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+	else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+	return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+//#endregion
+export { __decorate as default };

package/dist/_virtual/_@oxc-project_runtime@0.148.0/helpers/esm/decorateMetadata.js

@@ -0,0 +1,6 @@
+//#region \0@oxc-project+runtime@0.148.0/helpers/esm/decorateMetadata.js
+function __decorateMetadata(k, v) {
+	if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+}
+//#endregion
+export { __decorateMetadata as default };

package/dist/index.js

@@ -0,0 +1,63 @@
+import config, { frontendConfigSchema } from "./nodefony/config/config.js";
+import { defineFrontendConfig, frontendConfigJsonSchema } from "./nodefony/config/defineModuleConfig.js";
+import { FrontendError, FrontendNoEntriesError, FrontendPresetUnknownError, FrontendSupervisorStartError } from "./nodefony/src/errors/FrontendError.js";
+import react19Preset from "./nodefony/src/presets/react19-vite.js";
+import vue3Preset from "./nodefony/src/presets/vue3-vite.js";
+import angularPreset from "./nodefony/src/presets/angular-vite.js";
+import vanillaPreset from "./nodefony/src/presets/vanilla-vite.js";
+import svelte5Preset from "./nodefony/src/presets/svelte5-vite.js";
+import { ViteBuilder } from "./nodefony/src/builders/ViteBuilder.js";
+import { ViteConfigGenerator } from "./nodefony/service/ViteConfigGenerator.js";
+import { ViteProcessSupervisor } from "./nodefony/service/ViteProcessSupervisor.js";
+import { TemplateHelper } from "./nodefony/src/template/TemplateHelper.js";
+import __decorateMetadata from "./_virtual/_@oxc-project_runtime@0.148.0/helpers/esm/decorateMetadata.js";
+import __decorate from "./_virtual/_@oxc-project_runtime@0.148.0/helpers/esm/decorate.js";
+import FrontendService_default from "./nodefony/service/FrontendService.js";
+import { buildFrontendStatus, createFrontendAdminApi } from "./nodefony/src/FrontendAdminApi.js";
+import FrontendBuild from "./nodefony/command/frontend-build.js";
+import FrontendDev from "./nodefony/command/frontend-dev.js";
+import FrontendStatus from "./nodefony/command/frontend-status.js";
+import { Kernel, Module, services } from "nodefony";
+//#region index.ts
+let Frontend = class Frontend extends Module {
+	constructor(kernel) {
+		super("frontend", kernel, import.meta.url, config);
+		this.addCommand(FrontendBuild);
+		this.addCommand(FrontendDev);
+		this.addCommand(FrontendStatus);
+	}
+	/** JSON Schema de la config frontend → data plane admin (config riche Studio). */
+	configSchema() {
+		return frontendConfigJsonSchema();
+	}
+	/**
+	* Phase `onRegister` : valide la config (défauts + override `module-frontend`)
+	* via `defineFrontendConfig`, puis la ré-assigne à `this.options` AVANT
+	* l'instanciation du `@services` (`FrontendService` lit `module.options` à sa
+	* construction). Plante propre avec messages clairs si la config est invalide
+	* (convention Zod figée 2026-05-28).
+	*/
+	async onKernelRegister() {
+		this.options = defineFrontendConfig(this.options);
+		return this;
+	}
+	/**
+	* Phase `onBoot` : enregistre le producteur admin (`/nodefony/frontend/api/*`)
+	* auprès du broker, AVANT que framework ne monte le data plane à `onReady`.
+	* Handler lazy → le statut Vite est lu à la requête (superviseur démarré à
+	* `onServersReady`, bien après ce hook).
+	*/
+	async onKernelBoot() {
+		const registry = this.kernel?.container?.get("adminBroker");
+		const svc = this.kernel?.container?.get("frontend");
+		if (registry && svc && !registry.has("frontend")) registry.register(createFrontendAdminApi(svc));
+		return this;
+	}
+	async onKernelReady() {
+		return this;
+	}
+};
+Frontend = __decorate([services([FrontendService_default]), __decorateMetadata("design:paramtypes", [typeof Kernel === "undefined" ? Object : Kernel])], Frontend);
+var frontend_default = Frontend;
+//#endregion
+export { Frontend, FrontendError, FrontendNoEntriesError, FrontendPresetUnknownError, FrontendService_default as FrontendService, FrontendSupervisorStartError, TemplateHelper, ViteBuilder, ViteConfigGenerator, ViteProcessSupervisor, angularPreset, buildFrontendStatus, createFrontendAdminApi, frontend_default as default, defineFrontendConfig, frontendConfigJsonSchema, frontendConfigSchema, react19Preset, svelte5Preset, vanillaPreset, vue3Preset };

package/dist/nodefony/command/frontend-build.js

@@ -0,0 +1,68 @@
+import { Command } from "nodefony";
+import path from "node:path";
+import fs from "node:fs";
+//#region nodefony/command/frontend-build.ts
+const options = {
+	helpGroup: "FRONT ET RÉSEAU",
+	showBanner: false,
+	kernelEvent: "onReady"
+};
+/**
+* `nodefony frontend:build` — build production de tous les frontends déclarés.
+*
+* Écrit `public/dist/` + `manifest.json` par bundle (lu ensuite par
+* `renderProdTags` + servi par `server-static`).
+*
+* - Idempotent : un bundle déjà à jour est **ignoré** (relance prod rapide).
+*   `--force` rebuild tout.
+* - Erreurs : un bundle KO n'arrête pas les autres ; l'exit code passe à `1`
+*   s'il reste au moins un échec (cassure de pipeline CI).
+*/
+var FrontendBuild = class extends Command {
+	constructor(cli) {
+		super("frontend:build", "construit les fronts pour la production", cli, options);
+		this.addOption("-f, --force", "rebuild even if the manifest is up-to-date");
+	}
+	async generate() {
+		const opts = this.command?.opts?.() ?? {};
+		const svc = this.kernel?.container?.get("frontend");
+		if (!svc) {
+			this.log("service `frontend` not registered — is @nodefony/frontend loaded?", "ERROR");
+			process.exitCode = 1;
+			return this;
+		}
+		const entries = svc.listEntries();
+		if (entries.length === 0) {
+			this.log("no frontend entries declared", "WARNING");
+			console.log("frontend:build — aucun frontend déclaré, rien à construire.");
+			return this;
+		}
+		const lastBuilt = (name) => {
+			const e = entries.find((x) => x.entryName === name);
+			if (!e) return "?";
+			try {
+				return fs.statSync(path.join(e.outDir, ".vite", "manifest.json")).mtime.toLocaleString("fr-FR");
+			} catch {
+				return "jamais";
+			}
+		};
+		console.log(`frontend:build — ${entries.length} frontend(s)${opts.force ? " (--force)" : ""}…`);
+		try {
+			const res = await svc.build({ force: opts.force });
+			if (res.built.length) console.log(`  ✓ construit(s) : ${res.built.join(", ")}`);
+			for (const name of res.skipped) console.log(`  • à jour       : ${name} (dernier build ${lastBuilt(name)}) — rien à faire`);
+			for (const f of res.failures) console.log(`  ✗ ÉCHEC        : ${f.entryName} — ${f.message}`);
+			if (!res.built.length && !res.failures.length) console.log("  → tout est à jour. Rien à reconstruire (--force pour tout refaire).");
+			this.log(`built:[${res.built.join(", ") || "—"}] skipped:[${res.skipped.join(", ") || "—"}] failed:[${res.failures.map((f) => f.entryName).join(", ") || "—"}]`, res.failures.length ? "ERROR" : "INFO");
+			if (res.failures.length) process.exitCode = 1;
+		} catch (e) {
+			const msg = e instanceof Error ? e.message : String(e);
+			this.log(msg, "ERROR");
+			console.log(`frontend:build — ÉCHEC : ${msg}`);
+			process.exitCode = 1;
+		}
+		return this;
+	}
+};
+//#endregion
+export { FrontendBuild as default };

package/dist/nodefony/command/frontend-dev.js

@@ -0,0 +1,31 @@
+import { Command } from "nodefony";
+//#region nodefony/command/frontend-dev.ts
+const options = {
+	helpGroup: "FRONT ET RÉSEAU",
+	showBanner: false,
+	kernelEvent: "onReady"
+};
+/**
+* `nodefony frontend:dev` — démarre manuellement le superviseur Vite.
+*
+* Utile quand `autoStartInDevelopment: false` dans la config, ou pour
+* relancer le superviseur Vite manuellement.
+*/
+var FrontendDev = class extends Command {
+	constructor(cli) {
+		super("frontend:dev", "démarre le serveur Vite à la main", cli, options);
+	}
+	async generate() {
+		const svc = this.kernel?.container?.get("frontend");
+		if (!svc) {
+			this.log("service `frontend` not registered", "ERROR");
+			return this;
+		}
+		await svc.startDev();
+		const st = svc.status();
+		this.log(`vite dev server: ${st.host}:${st.port} [${st.state}]`, "INFO");
+		return this;
+	}
+};
+//#endregion
+export { FrontendDev as default };

package/dist/nodefony/command/frontend-status.js

@@ -0,0 +1,40 @@
+import { Command } from "nodefony";
+//#region nodefony/command/frontend-status.ts
+const options = {
+	helpGroup: "FRONT ET RÉSEAU",
+	showBanner: false,
+	kernelEvent: "onReady"
+};
+/**
+* `nodefony frontend:status` — lit l'état du superviseur Vite.
+*
+* Utilisé par Vision (Phase 10) pour afficher l'état du builder dans
+* son tableau de bord admin.
+*/
+var FrontendStatus = class extends Command {
+	constructor(cli) {
+		super("frontend:status", "l'état du superviseur des fronts", cli, options);
+		this.addOption("-j, --json", "output as JSON");
+	}
+	async generate(_arg, opts) {
+		const svc = this.kernel?.container?.get("frontend");
+		if (!svc) {
+			this.log("service `frontend` not registered", "ERROR");
+			return this;
+		}
+		const st = svc.status();
+		if (opts.json) process.stdout.write(JSON.stringify(st, null, 2) + "\n");
+		else {
+			console.log(`state    : ${st.state}`);
+			console.log(`endpoint : ${st.host}:${st.port}`);
+			if (st.origin && !st.origin.endsWith(`://${st.host}:${st.port}`)) console.log(`public   : ${st.origin}`);
+			console.log(`pid      : ${st.pid ?? "-"}`);
+			console.log(`entries  : ${st.entries.length}`);
+			for (const e of st.entries) console.log(`  · ${e.entryName} [${e.type}] ${e.entryFile}`);
+			if (st.lastError) console.log(`error    : ${st.lastError}`);
+		}
+		return this;
+	}
+};
+//#endregion
+export { FrontendStatus as default };

package/dist/nodefony/config/config.js

@@ -0,0 +1,65 @@
+import { z } from "zod";
+//#region nodefony/config/config.ts
+/**
+* @nodefony/frontend — CONFIGURATION DU MODULE (schéma Zod = source unique).
+*
+* ⭐ TL;DR : CE SCHÉMA EST LA CONFIG. Chaque `.default(...)` = la valeur d'usine ;
+* changer un défaut du module = ÉDITER ICI (et nulle part ailleurs). L'app, elle,
+* surcharge via `use("@nodefony/...", { … })` dans SON `nodefony.config.ts`.
+*
+* Ce module pilote Vite (builder + dev server) pour transpiler les frontends
+* déclarés par chaque module Nodefony :
+*
+*   { frontend: { type: "react19", entry: "./frontend/src/main.tsx" } }
+*
+* RÈGLE D'OR (ADR-0006) : ce fichier porte le **schéma Zod commenté** (type +
+* validation + défaut + doc) ET matérialise les défauts via `parse({})`. Aucune
+* valeur n'est re-tapée ailleurs. Le builder (`defineModuleConfig.ts` →
+* `defineFrontendConfig`) importe le schéma D'ICI (nœud bas : ce fichier
+* n'importe que `zod` → pas de cycle). La fusion + validation finale
+* (`défauts + module.options`) est faite dans `index.ts` au hook
+* `onKernelRegister` via `defineFrontendConfig` (plante propre si invalide).
+*
+* ⚠️ NE PAS éditer les défauts matérialisés en bas de fichier : modifier les
+* `.default(...)` du schéma. La doc de chaque champ (`.describe(...)`) est
+* surfacée dans le panneau de config Studio via `frontendConfigJsonSchema()`.
+*
+* Périmètre : config **module-level** (le dev server Vite + le build prod). La
+* config **par entrée** (`registerEntry(module, { entry, root, publicPath, … })`)
+* est une déclaration runtime du module consommateur, PAS de la config — donc
+* hors de ce schéma.
+*/
+const resilienceSchema = z.strictObject({
+	autoRestart: z.boolean().default(true).describe("Redémarre automatiquement le superviseur Vite sur crash inattendu. Défaut : true. Mettre `false` en CI pour faire échouer le pipeline sur un crash Vite au lieu de le masquer."),
+	maxRestarts: z.number().int().nonnegative().default(5).describe("Nombre maximal de tentatives de restart avant de passer en `state: \"errored\"`. Défaut : 5."),
+	restartBackoffBaseMs: z.number().int().positive().default(500).describe("Base du backoff exponentiel entre deux restarts (ms). Défaut : 500."),
+	restartBackoffMaxMs: z.number().int().positive().default(8e3).describe("Plafond du backoff exponentiel (ms). Défaut : 8000."),
+	healthCheckIntervalMs: z.number().int().nonnegative().default(3e4).describe("Intervalle entre deux health checks du dev server (ms). `0` désactive le health check. Défaut : 30000."),
+	healthCheckFailureThreshold: z.number().int().positive().default(3).describe("Nombre d'échecs consécutifs de health check avant de déclencher un restart. Défaut : 3."),
+	healthCheckTimeoutMs: z.number().int().positive().default(5e3).describe("Timeout d'un health check individuel (ms). Défaut : 5000."),
+	portRetryAttempts: z.number().int().positive().default(3).describe("Nombre de ports à essayer sur `EADDRINUSE` (devPort, devPort+1, …). Défaut : 3.")
+}).describe("Résilience du superviseur Vite (auto-restart, backoff, health check). Toutes optionnelles — les défauts internes s'appliquent si rien n'est fourni.");
+const frontendConfigSchema = z.strictObject({
+	devHost: z.string().default("127.0.0.1").describe("Host d'écoute du dev server Vite — utilisé tel quel dans les `<script>` injectés (doit être joignable depuis le navigateur). Prod : N/A (Vite ne tourne pas en prod, le manifest pilote)."),
+	devPort: z.number().int().positive().default(5173).describe("Port d'écoute du dev server Vite (5173 par défaut) — port de BASE : chaque famille de frontends prend le bloc suivant. Si occupé, c'est le SUPERVISEUR qui relance sur le port suivant (`resilience.portRetryAttempts` essais) et publie le port réel dans son `status()` — Vite, lui, ne se décale jamais seul : le fichier généré porte `strictPort` pour que l'origine annoncée au navigateur soit toujours celle qui sert."),
+	publicOrigin: z.string().default("").refine((v) => v === "" || /^https?:\/\/[^/\s]+$/.test(v), { message: "publicOrigin doit être une origine (`scheme://host[:port]`), sans chemin" }).describe("Origine PUBLIQUE du dev server Vite — celle que le NAVIGATEUR utilise, quand elle diffère de l'adresse d'écoute (`devHost`). ÉPINGLE le rendu sur une origine unique : à réserver aux cas où un frontal la réécrit (tunnel, proxy, port remappé). Utilisée telle quelle (port inclus SEULEMENT si écrit) dans les `<script>` injectés, le `base` Vite et le WebSocket HMR (`hmr.host`/`clientPort`, dérivés). Vide (défaut, RECOMMANDÉ) = chaque page annonce l'origine par laquelle le client est arrivé (`Host` de la requête, scheme et port de Vite) : un poste et un navigateur en conteneur sont servis EN MÊME TEMPS par la même instance, sans configuration — et Codespaces/Gitpod restent détectés automatiquement. L'hôte d'une origine épinglée est automatiquement autorisé par Vite (`server.allowedHosts`) ; les hôtes suivis par la dérivation sont ceux de `trustedHosts` de @nodefony/http (une seule liste à maintenir : elle ouvre la barrière 421, Vite, le CSP et le rendu)."),
+	autoStartInDevelopment: z.boolean().default(true).describe("Démarre automatiquement le superviseur Vite quand le kernel passe en `development`. Ignoré en `production`/`staging`. Reco : true en dev, sinon les helpers template injecteront une URL morte."),
+	defaultOutDir: z.string().default("./public/dist").describe("Dossier de sortie par défaut pour le build prod, relatif à la racine du module consommateur. Réécrit par la prop `outDir` de la déclaration d'entrée."),
+	defaultRoot: z.string().default("./frontend").describe("Racine front par défaut (contient `index.html`) côté module."),
+	assetBaseUrl: z.string().default("").describe("Base URL des assets servis en PRODUCTION (CDN / object storage / edge). Vide = assets servis depuis l'origine Nodefony en chemins relatifs (comportement historique). Renseignée (ex. `https://cdn.example.com`), elle préfixe le `base` Vite au build, les URLs de `renderProdTags` et le helper `asset('/x')`. N'affecte JAMAIS le mount `Statics`. Reco prod cloud-native : pointer le CDN devant l'object storage."),
+	startupTimeoutMs: z.number().int().positive().default(3e4).describe("Timeout (ms) d'attente du `Local: http://…` dans le stdout Vite avant de considérer le démarrage comme cassé. Dev : 30s suffisent pour un cold-start Vite. Prod : N/A."),
+	pipeViteLogs: z.boolean().default(true).describe("Propage les logs Vite vers le syslog Nodefony (sinon ils restent dans le stdout du process enfant uniquement)."),
+	backendHost: z.string().default("127.0.0.1").describe("Host du serveur Nodefony cible du proxy Vite (`server.proxy`). Quand le navigateur fait `fetch(\"/api/...\")` depuis la page servie par Vite, Vite proxifie vers `${backendProtocol}://${backendHost}:${backendPort}`."),
+	backendPort: z.number().int().positive().default(5151).describe("Port du serveur Nodefony cible du proxy Vite. HTTP par défaut (5151, config par défaut de `@nodefony/http`). Ajuster si l'app surcharge."),
+	backendProtocol: z.enum(["http", "https"]).default("http").describe("Protocole du proxy Vite vers Nodefony. `http` par défaut — `https` pour proxifier vers le serveur HTTPS Nodefony (5152). Avec `https` et un certificat self-signed, prévoir `secure: false` côté proxy."),
+	https: z.boolean().default(false).describe("Active HTTPS pour le dev server Vite (récupère les certificats du service `certificates` de `@nodefony/http`, mêmes certs que `server-https` 5152). Reco : true quand la page Nodefony est servie en HTTPS (5152) — évite le warning mixed-content. Le navigateur demandera la confiance pour 5173 si la CA root Nodefony n'est pas installée localement."),
+	viteEnv: z.record(z.string(), z.string()).default({}).describe("Variables d'environnement supplémentaires passées au child Vite. Les clés préfixées `VITE_` sont exposées au navigateur via `import.meta.env.VITE_*` (ex. `{ VITE_API_BASE: \"/api/v1\" }`). Reco prod : utiliser un `.env.production` dans le `root` Vite plutôt que cette option, pour ne pas leak de secrets dans le code Nodefony."),
+	resilience: resilienceSchema.default(() => resilienceSchema.parse({}))
+}).describe("Configuration de @nodefony/frontend (dev server Vite + build prod).");
+/**
+* Défauts du module, matérialisés depuis le schéma (source unique). Toujours
+* valides par construction ; passés au `super(..., config)` du Module class.
+*/
+const config = frontendConfigSchema.parse({});
+//#endregion
+export { config as default, frontendConfigSchema };

package/dist/nodefony/config/defineModuleConfig.js

@@ -0,0 +1,34 @@
+import { frontendConfigSchema } from "./config.js";
+import { parseModuleConfig } from "nodefony";
+import { z } from "zod";
+//#region nodefony/config/defineModuleConfig.ts
+/**
+* Builder type-safe de la configuration de `@nodefony/frontend`.
+*
+* ⭐ TL;DR : MACHINERIE DE BOOT — on n'édite (presque) jamais ce fichier. Même
+* pattern que `nodefony.config.ts` ↔ `defineConfig()` du core : `config.ts` PORTE
+* la config (schéma + défauts), `define<X>Config()` la VALIDE au boot (parse +
+* env + freeze) et publie le JSON Schema Studio.
+*
+* Principes (alignés sur `defineRealtimeConfig` / famille ORM) :
+* - **Source unique** : `./config.ts` (Zod). Le builder VALIDE + GÈLE, ne dévie pas.
+* - **Auto-documenté + introspectable** : chaque champ Zod porte `.describe()` →
+*   {@link frontendConfigJsonSchema} produit un JSON Schema que le panneau de
+*   config Studio consomme.
+*
+* @param config - configuration brute (sections omises = défauts sûrs).
+* @returns config gelée prête pour `FrontendService`.
+* @throws ZodError si invalide.
+*/
+function defineFrontendConfig(config = {}) {
+	return Object.freeze(parseModuleConfig(frontendConfigSchema, config, "@nodefony/frontend"));
+}
+/**
+* JSON Schema introspectable de la config frontend — destiné au panneau de config
+* Studio (`/nodefony/config`).
+*/
+function frontendConfigJsonSchema() {
+	return z.toJSONSchema(frontendConfigSchema);
+}
+//#endregion
+export { defineFrontendConfig, frontendConfigJsonSchema };

package/dist/nodefony/interfaces/IFrontBuilder.js

@@ -0,0 +1 @@
+export {};