@nodefony/frontend 10.0.0-alpha.1

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

@@ -0,0 +1,89 @@
+/**
+ * Famille d'isolation Vite d'un type de preset frontend.
+ *
+ * Les presets d'une même famille **cohabitent dans une seule instance Vite** ;
+ * les familles distinctes tournent dans des **process Vite séparés** (multi-
+ * supervisor).
+ *
+ * **Le motif est toujours le même : un plugin qui transforme ce qui ne lui
+ * appartient pas.** Deux familles le paient aujourd'hui.
+ *
+ * Angular : son plugin (`@analogjs/vite-plugin-angular`) transforme **tout**
+ * fichier `.ts` du serveur de développement — y compris ceux des autres bundles
+ * (ex. stores MobX à décorateurs). Mélangé aux autres, il throw sur des fichiers
+ * hors de son tsconfig → erreurs de compilation + boucle de rechargement.
+ *
+ * Vue : le compilateur de composants monofichiers sert le bloc script sous un
+ * identifiant qui se TERMINE par `.ts`
+ * (`App.vue?vue&type=script&setup=true&lang.ts`). Le filtre de
+ * `@vitejs/plugin-react` y mord — il est élargi aux identifiants portant une
+ * query — et injecte son `$RefreshSig$()`, que rien ne définit sur une page sans
+ * préambule React : la vitrine Vue ne se montait plus du tout
+ * (`ReferenceError: $RefreshSig$ is not defined`).
+ *
+ * ⚠️ Il a longtemps été écrit ici que « React / Vue / vanilla ciblent des
+ * extensions disjointes ». C'était faux, et c'est ce qui a fait chercher
+ * ailleurs. Passer `exclude: [/\.vue/]` à `@vitejs/plugin-react` **ne suffit
+ * pas** : mesuré sur Vite 8.2.2, l'injection persiste jusqu'à `exclude: [/./]`
+ * inclus — l'option ne borne pas ce chemin. Seule l'isolation en process
+ * distinct l'arrête.
+ *
+ * Svelte, lui, cohabite sans dommage (constaté) : son bloc script n'est pas
+ * servi sous un identifiant qui finit par `.ts`.
+ *
+ * @param type - type de preset déclaré par le module (`react19`, `vue3`,
+ *   `angular`, `vanilla`, …).
+ * @returns la clé de famille d'isolation (`"default"` pour tout ce qui peut
+ *   partager une instance, une clé dédiée pour ce qui doit être isolé).
+ */
+export declare function isolationGroup(type: string): string;
+/**
+ * Famille servie sur le port de base (`devPort`). Les autres familles prennent
+ * les blocs de ports suivants. Garder `default` ici garantit que l'instance
+ * principale (React/Vue/Studio) reste sur le port habituel (5173).
+ */
+export declare const PRIMARY_FAMILY = "default";
+/**
+ * Ordonne les familles de façon déterministe : la famille primaire d'abord
+ * (port de base), puis les autres triées alphabétiquement. L'ordre fixe le
+ * port attribué à chaque famille — il doit être stable entre deux démarrages.
+ *
+ * @param families - familles présentes (clés de regroupement des entries).
+ * @returns familles ordonnées, `PRIMARY_FAMILY` en tête s'il est présent.
+ */
+export declare function orderFamilies(families: ReadonlyArray<string>): string[];
+/**
+ * Plan d'allocation des ports : un **bloc disjoint** par famille. Chaque famille
+ * réserve `portRetryAttempts + 1` ports consécutifs → le port-retry d'une
+ * instance (sur EADDRINUSE) ne peut jamais empiéter sur le bloc d'une autre
+ * famille. La famille primaire (index 0) garde `devPort` (le port habituel).
+ *
+ * @param devPort - port de base de la première famille (ex. 5173).
+ * @param families - familles présentes ; réordonnées en interne via `orderFamilies`.
+ * @param portRetryAttempts - tentatives de port-retry par instance (bloc = +1).
+ * @returns map ordonnée `famille → port de base de son bloc`.
+ */
+export declare function familyPortPlan(devPort: number, families: ReadonlyArray<string>, portRetryAttempts: number): Map<string, number>;
+/**
+ * Bloc de ports de chaque famille : tous les ports que SON instance Vite peut
+ * prendre, port-retry compris.
+ *
+ * Le plan seul ne dit que le port ESPÉRÉ ; sur `EADDRINUSE` le superviseur
+ * glisse dans son bloc. Un CSP construit sur le seul port espéré laisse la page
+ * sans rechargement à chaud dès que le port de base est pris — et il l'est dès
+ * qu'un second projet tourne sur la machine.
+ *
+ * Rendu par famille, et non à plat : le consommateur remplace le bloc d'une
+ * famille par son port RÉEL dès qu'il est connu. Déclarer les douze ports d'un
+ * poste à trois familles coûte un en-tête CSP de ~8 Ko sur chaque réponse
+ * (mesuré) — la plage est le prix d'une incertitude, elle ne doit pas survivre
+ * à sa levée.
+ *
+ * Dérivé du plan plutôt que recalculé depuis `devPort` : la règle des blocs
+ * disjoints n'est écrite qu'à un endroit, `familyPortPlan`.
+ *
+ * @param plan - `famille → port de base`, tel que rendu par `familyPortPlan`.
+ * @param portRetryAttempts - tentatives de port-retry par instance (bloc = +1).
+ * @returns `famille → ports du bloc`, croissants.
+ */
+export declare function familyPortBlocks(plan: ReadonlyMap<string, number>, portRetryAttempts: number): Map<string, number[]>;

package/dist/types/nodefony/src/presets/angular-vite.d.ts

@@ -0,0 +1,15 @@
+import type { IFrontPreset } from "../../interfaces/IFrontPreset.js";
+/**
+ * Preset Angular (17+ standalone) + Vite via `@analogjs/vite-plugin-angular`.
+ *
+ * Charge le plugin paresseusement : aucune dépendance Angular tant qu'aucune
+ * entrée `angular` n'est déclarée. Comme React/Vue, aucun preamble HTML n'est
+ * requis — `bootstrapApplication(AppComponent)` dans le point d'entrée suffit.
+ *
+ * ⚠️ Contrairement à `.vue`/`.tsx`, le plugin Angular transforme les `.ts`
+ * (extension non dédiée). Le scoping se fait via le `tsconfig` de l'app Angular
+ * (passé par `ViteConfigGenerator`) dont le `include` ne couvre que le frontend
+ * Angular — les `main.ts` des autres bundles (Vue) restent hors programme.
+ */
+declare const angularPreset: IFrontPreset;
+export default angularPreset;

package/dist/types/nodefony/src/presets/react19-vite.d.ts

@@ -0,0 +1,9 @@
+import type { IFrontPreset } from "../../interfaces/IFrontPreset.js";
+/**
+ * Preset React 19 + Vite.
+ *
+ * Charge `@vitejs/plugin-react` paresseusement : aucune dépendance
+ * sur le module si aucune entrée React n'est déclarée.
+ */
+declare const react19Preset: IFrontPreset;
+export default react19Preset;

package/dist/types/nodefony/src/presets/svelte5-vite.d.ts

@@ -0,0 +1,13 @@
+import type { IFrontPreset } from "../../interfaces/IFrontPreset.js";
+/**
+ * Preset Svelte 5 + Vite.
+ *
+ * Charge `@sveltejs/vite-plugin-svelte` paresseusement : aucune dépendance sur
+ * le module tant qu'aucune entrée Svelte n'est déclarée — c'est l'application
+ * qui porte `svelte` et le plugin en devDependencies. Comme Vue, Svelte n'exige
+ * aucun preamble HMR injecté côté serveur (`mount(App, { target })` suffit) ;
+ * il cohabite donc dans la famille d'isolation `default` (extensions `.svelte`
+ * disjointes de `.tsx`/`.vue`).
+ */
+declare const svelte5Preset: IFrontPreset;
+export default svelte5Preset;

package/dist/types/nodefony/src/presets/vanilla-vite.d.ts

@@ -0,0 +1,9 @@
+import type { IFrontPreset } from "../../interfaces/IFrontPreset.js";
+/**
+ * Preset vanilla — TS/JS sans framework.
+ *
+ * Aucun plugin Vite, utile pour les modules qui n'ont besoin
+ * que de bundling ESM + HMR de base.
+ */
+declare const vanillaPreset: IFrontPreset;
+export default vanillaPreset;

package/dist/types/nodefony/src/presets/vue3-vite.d.ts

@@ -0,0 +1,11 @@
+import type { IFrontPreset } from "../../interfaces/IFrontPreset.js";
+/**
+ * Preset Vue 3 + Vite.
+ *
+ * Charge `@vitejs/plugin-vue` paresseusement : aucune dépendance
+ * sur le module tant qu'aucune entrée Vue n'est déclarée. Contrairement
+ * à React, Vue ne nécessite aucun preamble HMR injecté côté serveur —
+ * `createApp(App).mount(...)` dans le point d'entrée suffit.
+ */
+declare const vue3Preset: IFrontPreset;
+export default vue3Preset;

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

@@ -0,0 +1,107 @@
+/**
+ * Dev déporté (P14.17) — calculs PURS d'origine publique du dev server Vite.
+ *
+ * Le problème résolu : `devHost` est une adresse d'ÉCOUTE ; l'origine que le
+ * NAVIGATEUR utilise peut être toute autre chose — un forwarder TLS (Codespaces,
+ * Gitpod), une passerelle de conteneur (`host.docker.internal`), un port remappé.
+ * Ce module dissocie les deux : il produit l'origine publique (assets, `base`
+ * Vite, WebSocket HMR) à partir d'un TEMPLATE (`{port}` substitué au port réel
+ * du spawn) — explicite (`frontend.publicOrigin`) ou détecté depuis
+ * l'environnement de la plateforme.
+ *
+ * Tout est pur et injectable (env en paramètre) : testable sans process, sans
+ * réseau, sur les trois plateformes.
+ *
+ * Formats VÉRIFIÉS (docs officielles + source Vite 8) :
+ *  - Codespaces : `https://${CODESPACE_NAME}-${port}.${GITHUB_CODESPACES_PORT_FORWARDING_DOMAIN}`
+ *    (TLS terminé par le forwarder → WS HMR en `wss` sur 443).
+ *  - Gitpod classic : `https://${port}-<hôte de GITPOD_WORKSPACE_URL>`.
+ *  - Vite `server.allowedHosts` : IP et `localhost`/`*.localhost` TOUJOURS
+ *    acceptés ; un préfixe `.` = le domaine ET tous ses sous-domaines.
+ *  - VS Code Remote / dev containers / WSL2 : forwarding sur `localhost` →
+ *    les défauts locaux suffisent, aucune détection requise.
+ */
+/** Placeholder substitué par le port réel du spawn dans un template d'origine. */
+export declare const PORT_PLACEHOLDER = "{port}";
+/** Résultat d'un template résolu contre un port réel. */
+export interface IResolvedPublicOrigin {
+    /** Origine que le navigateur utilise — verbatim dans les `<script>` et le `base` Vite. */
+    readonly origin: string;
+    /**
+     * Config `server.hmr` cliente : le WS HMR doit suivre le MÊME chemin que les
+     * assets. Port implicite → 443/80 selon le scheme (cas forwarder TLS).
+     */
+    readonly hmr: {
+        readonly host: string;
+        readonly clientPort: number;
+        readonly protocol: "ws" | "wss";
+    };
+}
+/** Environnement de dev déporté détecté depuis les variables de la plateforme. */
+export interface IRemoteDevDetection {
+    readonly provider: "codespaces" | "gitpod";
+    /** Template d'origine publique du dev server Vite (`{port}` à substituer). */
+    readonly originTemplate: string;
+}
+/**
+ * Hôte utilisable par un NAVIGATEUR pour une adresse d'écoute donnée.
+ * `0.0.0.0`/`::` sont des adresses d'ÉCOUTE (toutes interfaces), pas des
+ * destinations : dérivées telles quelles dans une URL, elles donnent des
+ * `<script src="http://0.0.0.0:5173/…">` que les navigateurs refusent — et
+ * sous Windows, une CONNEXION vers `0.0.0.0` échoue aussi (health check).
+ */
+export declare function browserReachableHost(listenHost: string): string;
+/** Un template d'origine est-il syntaxiquement valide ? (autorité unique) */
+export declare function isValidOriginTemplate(template: string): boolean;
+/**
+ * Rejoue une origine résolue sur un AUTRE nom d'hôte, en conservant le scheme
+ * et le port. Pure.
+ *
+ * C'est le cœur de la dérivation par requête : le scheme et le port sont ceux
+ * du serveur Vite (il écoute où il écoute), seul le NOM change — celui par
+ * lequel le client est arrivé. Une page servie sur `http://poste:5151` charge
+ * donc `https://poste:5173` si Vite est en TLS : le scheme ne se déduit JAMAIS
+ * de la page.
+ *
+ * `new URL()` est volontairement évité (une allocation par page rendue, pour
+ * une chaîne dont nous produisons nous-mêmes la grammaire).
+ *
+ * @param origin - origine résolue (`scheme://hôte[:port]`).
+ * @param hostname - nom d'hôte de remplacement, SANS port (`Context.domain`) ;
+ *   une IPv6 est acceptée sous sa forme canonique entre crochets (`[::1]`).
+ * @returns l'origine réécrite, ou `null` si l'un des deux est inexploitable
+ *   (l'appelant garde alors l'origine d'origine — jamais d'URL bancale émise).
+ */
+export declare function originWithHostname(origin: string, hostname: string): string | null;
+/**
+ * Résout un template d'origine contre le port RÉEL du spawn. Pure.
+ *
+ * @returns origine + config HMR cliente, ou `null` si le template est invalide
+ *   (l'appelant retombe sur la dérivation locale en l'ANNONÇANT — jamais en
+ *   silence).
+ */
+export declare function resolveOriginTemplate(template: string, port: number): IResolvedPublicOrigin | null;
+/**
+ * Motif `server.allowedHosts` couvrant TOUTES les origines qu'un template peut
+ * produire. `{port}` dans l'hôte → le sous-domaine varie avec le port : motif
+ * `.suffixe` (wildcard Vite = domaine + sous-domaines). Hôte fixe → verbatim.
+ *
+ * @returns le motif, ou `null` si template invalide ou hôte non exprimable
+ *   (un `{port}` dans le DERNIER label n'a pas de suffixe à wildcarder).
+ */
+export declare function allowedHostPatternForTemplate(template: string): string | null;
+/**
+ * Motif Vite `allowedHosts` équivalent d'un pattern `trustedHosts` http.
+ * `*.suffixe` (wildcard un-label de la barrière Host) → `.suffixe` (wildcard
+ * Vite). Un `*` ailleurs n'est pas exprimable chez Vite → `null` (l'hôte reste
+ * couvert par la barrière Nodefony ; Vite le refusera — motif à écrire en
+ * clair dans `trustedHosts` si le cas se présente).
+ */
+export declare function viteAllowedHostFromPattern(pattern: string): string | null;
+/**
+ * Détecte un environnement de dev déporté depuis les variables de plateforme
+ * (variables qu'on ne possède pas — elles se lisent, ne se renomment pas).
+ * Ordre : Codespaces puis Gitpod (jamais les deux posées en pratique).
+ * Env local/VS Code Remote/WSL2 → `null` (les défauts locaux suffisent).
+ */
+export declare function detectRemoteDev(env: Readonly<Record<string, string | undefined>>): IRemoteDevDetection | null;

package/dist/types/nodefony/src/template/TemplateHelper.d.ts

@@ -0,0 +1,99 @@
+import type { IViteSupervisor } from "../../interfaces/IViteSupervisor.js";
+import type { IResolvedFrontendEntry } from "../../interfaces/IFrontBuilder.js";
+/**
+ * Génère les balises HTML à injecter dans la page rendue côté serveur
+ * pour brancher le frontend Vite.
+ *
+ * Dev : `<script type="module" src="http://host:port/@vite/client">` + entry.
+ * Prod : lira `manifest.json` du build pour les chemins fingerprintés (TODO).
+ */
+export declare class TemplateHelper {
+    private readonly supervisor;
+    private readonly mode;
+    private readonly entries;
+    private readonly assetBaseUrl;
+    /**
+     * Manifests Vite parsés, cachés par `outDir` (lecture disque 1× par bundle).
+     * `null` = lecture tentée mais manifest absent/illisible (build manquant).
+     */
+    private readonly manifestCache;
+    /** `index.html` des modules, caché par `root` (prod only — dev re-lit). */
+    private readonly indexCache;
+    /**
+     * @param supervisor superviseur Vite (dev) — `null` en prod (Vite ne tourne pas).
+     * @param mode bascule dev (URLs vers le dev server) / prod (manifest).
+     * @param entries entrées résolues — requises en prod pour `outDir`/`publicPath`.
+     * @param assetBaseUrl base CDN normalisée (sans slash final) préfixant les URLs
+     *   prod émises ; `""` = origine Nodefony (chemins relatifs).
+     */
+    constructor(supervisor: IViteSupervisor | null, mode: "development" | "production", entries?: ReadonlyArray<IResolvedFrontendEntry>, assetBaseUrl?: string);
+    /**
+     * Tags à injecter dans `<head>` (ou avant `</body>`) pour une entrée donnée.
+     * @param entryName nom logique de l'entrée (matche `entryName` dans IResolvedFrontendEntry)
+     * @param nonce nonce CSP de la requête (`Context.cspNonce`) — posé sur les `<script>`
+     *   pour satisfaire `script-src 'nonce-…'` (preamble inline dev + entrée prod).
+     * @param requestHost nom d'hôte par lequel le client a demandé la PAGE
+     *   (`Context.domain`, sans port). Dev : l'origine des assets est réécrite
+     *   sur ce nom (scheme et port restent ceux de Vite) → poste et conteneur
+     *   servis par la même instance. Prod : **ignoré** — les URLs du manifest
+     *   sont relatives au document, elles suivent déjà l'hôte de la page.
+     */
+    renderTags(entryName: string, nonce?: string, requestHost?: string): string;
+    /**
+     * Document HTML complet pour une entrée : lit l'`index.html` du module (le dev
+     * y met SES meta/polices/scripts externes), retire le `<script type=module>`
+     * de l'entrée source (Vite-native, non résolvable quand Nodefony sert la page)
+     * et injecte les tags Nodefony — au marqueur `<!--nodefony:frontend-->` sinon
+     * avant `</head>`. Pas d'`index.html` → coquille minimale générée.
+     *
+     * @param entryName nom logique de l'entrée
+     */
+    renderDocument(entryName: string, nonce?: string, requestHost?: string): string;
+    /** Injecte `tags` dans `html` (marqueur > `</head>` > `</body>` > append). */
+    private injectIntoHtml;
+    /**
+     * Lit `${root}/index.html`. Caché par root en **prod** (hot path) ; en dev,
+     * re-lu à chaque appel pour refléter les éditions du shell. `null` si absent.
+     */
+    private loadIndexHtml;
+    private renderDevTags;
+    /**
+     * Pont HMR sans socket : relaie les événements globaux de Vite
+     * (`vite:afterUpdate`, etc.) vers un `CustomEvent` `nodefony:hmr` sur `window`,
+     * que la debug bar écoute. `createHotContext` réutilise le client HMR déjà
+     * ouvert par `@vite/client` — zéro connexion ajoutée. Tolérant aux versions
+     * (try/catch) : si l'export change, le compteur HMR reste à 0 sans casser la page.
+     */
+    private hmrBridgeTag;
+    /**
+     * Tag d'injection de la debug bar (subpath `nodefony/debugbar`). Résout le
+     * fichier dist navigateur côté serveur (1×, caché) et le sert via `/@fs`.
+     * Renvoie un commentaire HTML (jamais d'erreur) si le subpath est irrésoluble.
+     */
+    private debugBarTag;
+    /**
+     * Prod : lit le `manifest.json` du build Vite (caché par `outDir`) et injecte
+     * les assets fingerprintés du chunk d'entrée — JS + CSS + preload des imports
+     * partagés — préfixés par le `publicPath` de l'entrée (servi par `Statics`).
+     */
+    private renderProdTags;
+    /**
+     * Lit + parse `${outDir}/.vite/manifest.json` (Vite ≥5) une seule fois par
+     * `outDir`. Retombe sur `${outDir}/manifest.json` (layout legacy).
+     *
+     * Un manifest TROUVÉ est caché (hot path : zéro disque par requête). Un
+     * manifest ABSENT n'est JAMAIS caché : figer l'absence condamnait le serveur
+     * à la page blanche jusqu'au restart, même après un `frontend:build` réussi
+     * (vécu). Le coût — 2 lectures ratées par rendu — n'existe que dans l'état
+     * dégradé « pas de build », qui n'est pas un hot path à défendre ; dès que
+     * le build apparaît, la lecture réussit et le cache reprend.
+     */
+    private loadManifest;
+    /**
+     * Collecte récursivement les fichiers CSS d'un chunk + de ses imports
+     * (le CSS d'un chunk partagé doit être chargé par toutes les entrées).
+     * Dédup via un `Set`, anti-cycle via l'ensemble des clés visitées.
+     */
+    private collectCss;
+}
+export default TemplateHelper;