vite-plugin-milpa 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 @Calcifux (Carlos Guillermo Reyes Ramiro)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,101 @@
+# vite-plugin-milpa
+
+> Vite integration for the [milpa](https://pypi.org/project/milpa-core/) framework (FastAPI + Jinja),
+> in the spirit of `laravel-vite-plugin`. Docs below in Spanish — milpa's home language.
+
+El `laravel-vite-plugin` de **milpa**: conecta tu app Vite (React, Vue, Svelte, vanilla…)
+con el backend milpa, que sirve el shell Jinja e inyecta tus assets con su helper `vite()`.
+
+```js
+// vite.config.js — todo el pegamento en una llamada
+import {defineConfig} from 'vite';
+import react from '@vitejs/plugin-react';
+import {milpa} from 'vite-plugin-milpa';
+
+export default defineConfig({
+    plugins: [
+        react(),
+        milpa({
+            entry: 'src/main.jsx',
+            pwa: {shell: '/spa'}, // opcional — omite para un SPA sin PWA
+        }),
+    ],
+});
+```
+
+```jinja
+{# El template Jinja de TU app (milpa lo sirve) #}
+{{ vite_react_refresh(app='demo-spa') }}
+{{ vite('src/main.jsx', app='demo-spa') }}
+```
+
+## Qué hace
+
+1. **`base` + `build.manifest` + entry** — lo que el helper `vite()` de milpa necesita para
+   emitir `<link>`/`<script>` hasheados en prod. La base se deriva de la carpeta:
+   `surcos/<app>` → `/vite/<app>/`.
+2. **Build a `public/<app>` del proyecto** (estilo `mix.js` → `public/` de Laravel): milpa
+   monta `public/` completo y un solo mount sirve a todas las apps.
+3. **Hot-file (modelo Laravel)** — `npm run dev` escribe `./hot` con la URL real del dev
+   server y lo borra al apagarse; milpa decide dev/prod por su existencia. Un hot-file POR
+   app: tu equipo en dev con HMR mientras los demás corren su build.
+4. **PWA opcional** ([Serwist](https://serwist.pages.dev) `injectManifest`) — compila
+   `src/sw.js` a un `sw.js` ESTÁTICO junto al build, precachea el shell del backend y
+   prefija los precache entries con la base (los relativos 404ean bajo subpath). Solo en
+   build: en dev el SW pelearía con HMR.
+5. **`ASSET_URL`** (env, solo build) — se antepone a la base derivada, igual que en
+   laravel-vite-plugin: deploy bajo sub-ruta de reverse proxy (`ASSET_URL=/nombre-reverse`)
+   o CDN, sin tocar el vite.config. Es la MISMA env var que lee el backend milpa en runtime.
+
+## Opciones
+
+| Opción | Default | Qué controla |
+|---|---|---|
+| `entry` | `'src/main.jsx'` | Entry point (va a `rollupOptions.input`) |
+| `assetsUrl` | `${ASSET_URL}/vite/<carpeta>` | URL pública donde milpa sirve esta app |
+| `publicDir` | `'../../public'` | `public/` del proyecto, relativo a la app |
+| `hotFile` | `'hot'` | Ruta del hot-file, relativa a la app |
+| `pwa` | `false` | `false` \| `{swSrc, swDest, shell, globDirectory}` |
+
+Nada es mandatorio: cualquier opción se overridea, o no uses el plugin y configura a mano —
+milpa solo necesita el manifest, la base y el hot-file.
+
+## `vite-plugin-milpa/router` — file-based routing (react-router 7)
+
+El subpath **runtime** del paquete (mismo patrón que `@serwist/vite/worker`): rutas por
+convención de archivos para `createBrowserRouter` (modo library — el que usa un SPA servido
+por un backend), sin plugin extra, sin codegen, sin virtual modules. ~70 líneas auditables.
+
+```js
+// src/router.jsx de TU app — los globs van en TU código (import.meta.glob es
+// compile-time y resuelve relativo al archivo que lo contiene):
+import {buildRoutes} from 'vite-plugin-milpa/router';
+
+const routes = buildRoutes({
+    pages:   import.meta.glob('./pages/**/*.jsx'),           // rutas core del shell
+    modules: import.meta.glob('./modules/*/pages/**/*.jsx'), // rutas por módulo /<m>/...
+});
+```
+
+| Convención | Resultado |
+|---|---|
+| `pages/acerca.jsx` | `/acerca` |
+| `pages/index.jsx` | `/` (índice de su carpeta) |
+| `pages/productos/[id].jsx` | `/productos/:id` (`useParams()`) |
+| `modules/tienda/pages/index.jsx` | `/tienda` (espejo de `Modules/<X>/Http` del backend) |
+| `modules/tienda/pages/_layout.jsx` | layout del módulo (envuelve sus rutas; opcional) |
+| `_loquesea.jsx` | ignorado (prefijo `_` = no-ruta) |
+
+Globs SIN eager ⇒ cada página es un chunk propio (code-splitting por ruta gratis). Acepta
+`.jsx/.tsx/.js/.ts`. Peers: `react >=18` y `react-router >=7` — **opcionales**: un surco
+vanilla usa el plugin sin React y sin warnings (solo los necesita quien importa `/router`).
+
+## El lado milpa
+
+Requiere milpa-core con el helper Vite (`Core/View/Vite.py`): settings `VITE_APPS_DIR`
+(default `surcos`), `VITE_PUBLIC_DIR` (default `public`), `VITE_ASSETS_URL` (default `/vite`).
+Sin apps detectadas, la integración simplemente no se activa.
+
+## Licencia
+
+[MIT](./LICENSE)

package/index.d.ts

@@ -0,0 +1,47 @@
+// Tipos de vite-plugin-milpa (el plugin build-time). El fuente es JS plano
+// auditable a propósito (lo que está en npm ES lo que corre); este .d.ts da el
+// soporte TypeScript de primera. Subpath runtime: ver router.d.ts.
+import type {Plugin} from 'vite';
+
+export interface MilpaPwaOptions {
+    /** Fuente del Service Worker, relativo a la app. Default: 'src/sw.js'. */
+    swSrc?: string;
+    /** Nombre del SW dentro del build. Default: 'sw.js'. */
+    swDest?: string;
+    /**
+     * Ruta del shell del backend a precachear (cold-start offline + fallback),
+     * p. ej. '/spa'. Bajo reverse proxy con sub-ruta, antepón el prefijo del
+     * deploy (es build-time, igual que la base de los chunks).
+     */
+    shell?: string;
+    /** Carpeta a globear para el precache. Default: el outDir del build. */
+    globDirectory?: string;
+}
+
+export interface MilpaOptions {
+    /** Entry de la app. Default: 'src/main.jsx'. */
+    entry?: string;
+    /**
+     * Base pública EXPLÍCITA de los assets (toma control total). Default
+     * derivada: `${ASSET_URL}/vite/<nombre-de-la-carpeta>/` — ASSET_URL es la
+     * misma env var que lee el backend milpa en runtime (deploy bajo sub-ruta
+     * de reverse proxy o CDN).
+     */
+    assetsUrl?: string | null;
+    /**
+     * Raíz public/ del PROYECTO backend (estilo Laravel), relativa a la app:
+     * el build cae en `<publicDir>/<app>/`. Default: '../../public'.
+     */
+    publicDir?: string;
+    /** Ruta del hot-file que decide dev/prod (modelo Laravel). Default: 'hot'. */
+    hotFile?: string;
+    /** PWA opcional con Serwist (injectManifest). Default: false. */
+    pwa?: boolean | MilpaPwaOptions;
+}
+
+/**
+ * TODO el pegamento backend-integration de milpa en una llamada (= el
+ * laravel-vite-plugin de milpa): base + manifest + outDir, hot-file para HMR,
+ * y PWA opcional. Cada opción se puede overridear; nada es mandatorio.
+ */
+export declare function milpa(options?: MilpaOptions): Plugin[];

package/index.js

@@ -0,0 +1,145 @@
+// vite-plugin-milpa — el "laravel-vite-plugin" de milpa (tu mix.js, pero mínimo).
+//
+// TODO el pegamento backend-integration en UNA llamada en vite.config.js:
+//
+//     import {milpa} from 'vite-plugin-milpa';
+//     export default defineConfig({
+//         plugins: [react(), milpa({pwa: {shell: '/spa'}})],
+//     });
+//
+// Qué hace por ti (cada pieza es lo que antes se configuraba a mano):
+//   1. base + build.manifest + rollupOptions.input → lo que el helper Jinja
+//      vite() de milpa necesita para emitir <link>/<script> hasheados.
+//      La base default se DERIVA de la carpeta: surcos/<app> → /vite/<app>/
+//      (la misma convención con la que milpa monta cada app — microfrontends).
+//   2. HOT-FILE (modelo Laravel): `npm run dev` escribe ./hot con la URL real
+//      del dev server y lo borra al apagarse; milpa decide dev/prod por su
+//      existencia. Un hot-file POR app: tu equipo en dev, los demás en build.
+//   3. PWA opcional (Serwist injectManifest): compila src/sw.js → dist/sw.js
+//      ESTÁTICO, precachea el shell del backend, y PREFIJA los entries con la
+//      base (gotcha real: salen relativos y 404earían bajo subpath). Solo en
+//      build — en dev el SW pelearía con HMR.
+//
+// Nada es mandatorio: cualquier opción se overridea, o no uses el plugin y
+// configura a mano — milpa solo necesita el manifest, la base y el hot-file.
+
+import {writeFileSync, rmSync} from 'node:fs';
+import {basename, resolve} from 'node:path';
+import {serwist} from '@serwist/vite';
+
+const DEFAULTS = {
+    entry: 'src/main.jsx',
+    assetsUrl: null,           // null => derivada: /vite/<nombre-de-la-carpeta>
+    publicDir: '../../public', // raíz public/ del PROYECTO (estilo Laravel): el build
+                               // de cada surco cae en public/<app>/ y milpa monta
+                               // public/ completo — relativo a la carpeta de la app.
+    hotFile: 'hot',
+    pwa: false,                // false | true | {swSrc, swDest, shell, ...}
+};
+
+export function milpa(userOptions = {}) {
+    const options = {...DEFAULTS, ...userOptions};
+    const plugins = [configPlugin(options), hotFilePlugin(options)];
+    if (options.pwa) plugins.push(...pwaPlugins(options));
+    return plugins;
+}
+
+// public/<app> de ESTA app (el outDir del build), relativo al root del frontend.
+function resolveOutDir(options, root) {
+    const appRoot = resolve(root ?? '.');
+    return resolve(appRoot, options.publicDir, basename(appRoot));
+}
+
+// La base de la app: explícita, o derivada de la carpeta (surcos/<app> → /vite/<app>/).
+// ASSET_URL (env, solo build) se antepone a la derivada — el MISMO env var que lee
+// el backend milpa en runtime, igual que laravel-vite-plugin: deploy bajo sub-ruta
+// de reverse proxy (ASSET_URL=/nombre-reverse) o CDN, sin tocar el vite.config.
+// Un assetsUrl explícito toma control total (no se le antepone nada).
+function resolveBase(options, root) {
+    const assetUrl = (process.env.ASSET_URL ?? '').replace(/\/+$/, '');
+    const url = options.assetsUrl ?? `${assetUrl}/vite/${basename(resolve(root ?? '.'))}`;
+    return url.endsWith('/') ? url : `${url}/`;
+}
+
+function configPlugin(options) {
+    return {
+        name: 'milpa:config',
+        config(config, {command}) {
+            return {
+                // En dev la base es '/' (los módulos salen del dev server);
+                // en build es donde milpa servirá dist/ (los chunks se
+                // referencian entre sí con esta base).
+                base: command === 'build' ? resolveBase(options, config.root) : '/',
+                build: {
+                    manifest: true,
+                    rollupOptions: {input: options.entry},
+                    // El build cae en public/<app> del PROYECTO (como mix.js a
+                    // public/ en Laravel). emptyOutDir explícito: Vite no limpia
+                    // solo los outDir fuera del root del frontend.
+                    outDir: resolveOutDir(options, config.root),
+                    emptyOutDir: true,
+                },
+            };
+        },
+        configResolved(config) {
+            // El root REAL queda disponible para los demás sub-plugins (el
+            // manifestTransform de la PWA lo necesita y corre fuera de un hook
+            // con config a la mano).
+            options._root = config.root;
+        },
+    };
+}
+
+function hotFilePlugin(options) {
+    let hotPath = options.hotFile;
+    return {
+        name: 'milpa:hot-file',
+        configResolved(config) {
+            hotPath = resolve(config.root, options.hotFile);
+        },
+        configureServer(server) {
+            server.httpServer?.once('listening', () => {
+                const address = server.httpServer.address();
+                const host = typeof address === 'object' && address.address !== '::' && address.address !== '0.0.0.0'
+                    ? address.address
+                    : 'localhost';
+                writeFileSync(hotPath, `http://${host}:${address.port}`);
+            });
+            const clean = () => {
+                rmSync(hotPath, {force: true});
+                process.exit();
+            };
+            process.once('SIGINT', clean);
+            process.once('SIGTERM', clean);
+            process.once('exit', () => rmSync(hotPath, {force: true}));
+        },
+    };
+}
+
+function pwaPlugins(options) {
+    const pwa = options.pwa === true ? {} : options.pwa;
+    const raw = serwist({
+        swSrc: pwa.swSrc ?? 'src/sw.js',
+        swDest: pwa.swDest ?? 'sw.js',
+        // Mismo destino que el build (public/<app>); se calcula desde el cwd del
+        // frontend (el gestor corre los scripts con cwd = carpeta de la app).
+        globDirectory: pwa.globDirectory ?? resolveOutDir(options, '.'),
+        injectionPoint: 'self.__SW_MANIFEST',
+        rollupFormat: 'iife',
+        // El shell HTML lo sirve el backend (no está en dist/): precachearlo da
+        // cold-start offline y el fallback de documentos del sw.js.
+        ...(pwa.shell ? {additionalPrecacheEntries: [{url: pwa.shell, revision: `${Date.now()}`}]} : {}),
+        // GOTCHA (docs/prerelease/26): los entries salen RELATIVOS y resuelven
+        // contra la URL del SW → 404 bajo subpath. Se prefijan con la base real.
+        manifestTransforms: [
+            (entries) => ({
+                manifest: entries.map((entry) => (
+                    entry.url.startsWith('/') ? entry : {...entry, url: `${resolveBase(options, options._root)}${entry.url}`}
+                )),
+            }),
+        ],
+    });
+    // El SW solo se genera en BUILD: en dev serviría assets stale y pelearía
+    // con HMR. `apply: 'build'` es el switch idiomático de Vite para esto.
+    return (Array.isArray(raw) ? raw : [raw]).map((plugin) => ({apply: 'build', ...plugin}));
+}

package/package.json

@@ -0,0 +1,70 @@
+{
+    "name": "vite-plugin-milpa",
+    "version": "0.1.0",
+    "description": "El toolkit frontend del framework milpa (FastAPI + Jinja), estilo laravel-vite-plugin: hot-file para HMR, manifest para el helper vite() de Jinja, multi-app (surcos/), PWA opcional con Serwist, ASSET_URL para deploy bajo sub-ruta/CDN — y file-based routing para react-router 7 vía `vite-plugin-milpa/router`.",
+    "type": "module",
+    "main": "index.js",
+    "types": "./index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./index.d.ts",
+            "default": "./index.js"
+        },
+        "./router": {
+            "types": "./router.d.ts",
+            "default": "./router.js"
+        }
+    },
+    "files": [
+        "index.js",
+        "index.d.ts",
+        "router.js",
+        "router.d.ts"
+    ],
+    "keywords": [
+        "vite-plugin",
+        "vite",
+        "milpa",
+        "fastapi",
+        "jinja",
+        "laravel-vite",
+        "backend-integration",
+        "pwa",
+        "serwist",
+        "microfrontends",
+        "file-based-routing",
+        "react-router"
+    ],
+    "author": "Calcifux (Carlos Guillermo Reyes Ramiro)",
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/calcifux/vite-plugin-milpa.git"
+    },
+    "homepage": "https://github.com/calcifux/vite-plugin-milpa#readme",
+    "bugs": {
+        "url": "https://github.com/calcifux/vite-plugin-milpa/issues"
+    },
+    "engines": {
+        "node": ">=18"
+    },
+    "volta": {
+        "node": "22.22.2"
+    },
+    "peerDependencies": {
+        "react": ">=18",
+        "react-router": ">=7",
+        "vite": ">=5"
+    },
+    "peerDependenciesMeta": {
+        "react": {
+            "optional": true
+        },
+        "react-router": {
+            "optional": true
+        }
+    },
+    "dependencies": {
+        "@serwist/vite": "^9.5.11"
+    }
+}

package/router.d.ts

@@ -0,0 +1,31 @@
+// Tipos de vite-plugin-milpa/router (el subpath RUNTIME: file-based routing
+// para react-router 7 en modo library). El fuente es JS plano auditable; los
+// globs los llama el CONSUMIDOR (import.meta.glob es compile-time y resuelve
+// relativo al archivo que lo contiene — no puede vivir en node_modules).
+import type {RouteObject} from 'react-router';
+
+/**
+ * El mapa que devuelve import.meta.glob SIN eager: archivo → loader perezoso.
+ * Cada loader se vuelve un chunk propio (code-splitting por ruta).
+ */
+export type GlobMap = Record<string, () => Promise<unknown>>;
+
+export interface BuildRoutesGlobs {
+    /**
+     * Glob de las páginas "core" del shell (carpeta pages/, recursivo).
+     * Convención: index → raíz de su carpeta, [id] → :id, prefijo _ → no-ruta.
+     */
+    pages?: GlobMap;
+    /**
+     * Glob de las páginas por módulo (modules/<m>/pages/, recursivo): cada
+     * módulo se monta bajo /<m>; su _layout (opcional) envuelve sus rutas.
+     * Espejo de los Modules/<X>/Http del backend milpa.
+     */
+    modules?: GlobMap;
+}
+
+/**
+ * Construye el árbol RouteObject[] de react-router desde tus globs. Llamar sin
+ * ninguno truena con instrucción (nunca falla en silencio).
+ */
+export declare function buildRoutes(globs?: BuildRoutesGlobs): RouteObject[];

package/router.js

@@ -0,0 +1,123 @@
+// vite-plugin-milpa/router — file-based routing para react-router 7 en modo
+// LIBRARY (createBrowserRouter), pensado para SPAs servidas por un backend
+// (milpa, Laravel, Django). Es el subpath RUNTIME del paquete: el plugin
+// (index.js) corre en Node al buildear; esto se bundlea DENTRO de tu app
+// (mismo patrón que @serwist/vite + @serwist/vite/worker).
+//
+// Convención (ESPEJO del backend milpa, que auto-monta Modules/<X>/Http):
+//
+//   pages/**/*               → rutas "core" del shell      /acerca
+//   modules/<m>/pages/**/*   → rutas del módulo <m>        /<m>/...
+//
+//   index.*     → la raíz de su carpeta ('' como segmento)
+//   [id].*      → segmento dinámico  :id  (useParams() en la página)
+//   _layout.*   → layout del módulo (envuelve sus rutas; opcional)
+//   _otro.*     → ignorado (prefijo '_' = no-ruta, como un parcial)
+//
+// 10 devs = 10 carpetas en modules/: cada quien dropea páginas en SU módulo y
+// la ruta existe — nadie toca un router central ni pisa al vecino.
+//
+// POR QUÉ recibe los globs en vez de llamarlos (la decisión clave del paquete):
+// import.meta.glob es compile-time de Vite y resuelve RELATIVO al archivo que lo
+// contiene — si viviera aquí (node_modules) globearía este paquete, no tus pages
+// (y Vite ni transforma globs cuyo importer está en node_modules; issue #2390).
+// El glob va en TU código; aquí solo se interpreta el mapa {archivo: loader}:
+//
+//     import {buildRoutes} from 'vite-plugin-milpa/router';
+//     const routes = buildRoutes({
+//         pages:   import.meta.glob('./pages/**/*.jsx'),
+//         modules: import.meta.glob('./modules/*/pages/**/*.jsx'),
+//     });
+//
+// Globs SIN eager devuelven () => import(...): cada página es un chunk propio
+// (code-splitting por ruta GRATIS, como el App Router de Next). Bonus: como el
+// glob es tuyo, este módulo NO depende de Vite — sirve cualquier bundler que
+// produzca el mismo mapa. JS plano sin JSX a propósito: createElement es el
+// equivalente compilado de <X/> y los bundlers NO parsean JSX en .js de
+// node_modules (esbuild: JSX solo en .jsx/.tsx; vite issue #8954).
+
+import {createElement, lazy} from 'react';
+
+// 'productos/[id].jsx' → 'productos/:id' · 'index.jsx' → '' · acepta .jsx/.tsx/.js/.ts
+function toPath(relativeFile) {
+    return relativeFile
+        .replace(/\.(jsx|tsx|js|ts)$/, '')
+        .split('/')
+        .map((segment) => (segment === 'index' ? '' : segment.replace(/^\[(.+)\]$/, ':$1')))
+        .filter(Boolean)
+        .join('/');
+}
+
+function lazyElement(loader) {
+    return createElement(lazy(loader));
+}
+
+function toRoute(path, loader) {
+    return path === '' ? {index: true, element: lazyElement(loader)} : {path, element: lazyElement(loader)};
+}
+
+// Basename con prefijo '_' = no-ruta (el _layout de módulo se trata aparte).
+function isHidden(relativeFile) {
+    return relativeFile.split('/').pop().startsWith('_');
+}
+
+const PAGES_RE = /\/pages\/(.+)$/;
+const MODULE_RE = /\/modules\/([^/]+)\/pages\/(.+)$/;
+const LAYOUT_RE = /^_layout\.(jsx|tsx|js|ts)$/;
+
+/**
+ * Construye el árbol de rutas (RouteObject[] de react-router) desde los mapas
+ * de import.meta.glob del CONSUMIDOR. Ambas claves son opcionales, pero llamar
+ * sin ninguna truena con instrucción (tenet milpa: nunca fallar en silencio).
+ */
+export function buildRoutes({pages, modules} = {}) {
+    if (pages === undefined && modules === undefined) {
+        throw new Error(
+            'buildRoutes necesita tus globs — en TU código (import.meta.glob resuelve relativo ' +
+                "al archivo que lo contiene): buildRoutes({pages: import.meta.glob('./pages/**/*.jsx'), " +
+                "modules: import.meta.glob('./modules/*/pages/**/*.jsx')}).",
+        );
+    }
+    const routes = [];
+
+    // Páginas core del shell (las del equipo "plataforma").
+    for (const [file, loader] of Object.entries(pages ?? {})) {
+        const match = file.match(PAGES_RE);
+        if (!match) {
+            throw new Error(`'${file}' no sigue la convención pages/ — ¿el glob de \`pages\` apunta a otra carpeta?`);
+        }
+        if (isHidden(match[1])) continue;
+        routes.push(toRoute(toPath(match[1]), loader));
+    }
+
+    // Páginas por módulo, agrupadas y montadas bajo /<modulo>.
+    const byModule = new Map();
+    const layouts = new Map();
+    for (const [file, loader] of Object.entries(modules ?? {})) {
+        const match = file.match(MODULE_RE);
+        if (!match) {
+            throw new Error(
+                `'${file}' no sigue la convención modules/<m>/pages/ — ¿el glob de \`modules\` apunta a otra carpeta?`,
+            );
+        }
+        const [, moduleName, relativeFile] = match;
+        if (LAYOUT_RE.test(relativeFile)) {
+            layouts.set(moduleName, loader); // no es página: es el wrapper del módulo
+            continue;
+        }
+        if (isHidden(relativeFile)) continue;
+        if (!byModule.has(moduleName)) byModule.set(moduleName, []);
+        byModule.get(moduleName).push(toRoute(toPath(relativeFile), loader));
+    }
+    for (const [moduleName, children] of byModule) {
+        const layoutLoader = layouts.get(moduleName);
+        routes.push({
+            path: moduleName,
+            // Sin _layout, react-router renderiza los hijos directo (<Outlet/> implícito).
+            ...(layoutLoader ? {element: lazyElement(layoutLoader)} : {}),
+            children,
+        });
+    }
+
+    return routes;
+}