@ressjs/vite-router 0.5.2 → 0.6.0-experimental.0

package/dist/routes/parse.js

@@ -0,0 +1,114 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseRoutePattern = parseRoutePattern;
+exports.pageIdFromFile = pageIdFromFile;
+exports.classifyEntry = classifyEntry;
+const EXTENSION = /\.(tsx|ts|jsx|js|mts|mjs)$/;
+function parseRoutePattern(sourceFile, pagesDir = 'app/pages') {
+    const relative = stripPagesDir(sourceFile, pagesDir).replace(EXTENSION, '');
+    const segments = [];
+    const paramNames = [];
+    const groups = [];
+    const parts = relative.split('/').filter(Boolean);
+    for (const [index, raw] of parts.entries()) {
+        // Un grupo organiza archivos sin aparecer en la URL.
+        if (raw.startsWith('(') && raw.endsWith(')')) {
+            groups.push(raw.slice(1, -1));
+            continue;
+        }
+        // `index` nombra la ruta de su carpeta, así que no aporta segmento propio.
+        if (raw === 'index' && index === parts.length - 1)
+            continue;
+        const segment = parseSegment(raw, sourceFile);
+        // Todo lo que siga a un catch-all sería inalcanzable: el catch-all ya
+        // consumió el resto de la URL.
+        const previous = segments[segments.length - 1];
+        if (previous && (previous.kind === 'catchAll' || previous.kind === 'optionalCatchAll')) {
+            throw new Error(`[ress] "${sourceFile}" pone un segmento después de "[...${previous.value}]". ` +
+                'Un catch-all consume el resto de la URL, así que nada que lo siga puede alcanzarse.');
+        }
+        if (segment.kind !== 'static') {
+            if (paramNames.includes(segment.value)) {
+                throw new Error(`[ress] "${sourceFile}" usa el parámetro "${segment.value}" dos veces. ` +
+                    'Cada parámetro tiene que tener un nombre distinto para poder leerse.');
+            }
+            paramNames.push(segment.value);
+        }
+        segments.push(segment);
+    }
+    return { pattern: toPattern(segments), segments, paramNames, groups };
+}
+function parseSegment(raw, sourceFile) {
+    const open = raw.indexOf('[');
+    const close = raw.lastIndexOf(']');
+    if (open === -1 && close === -1)
+        return { kind: 'static', value: raw };
+    if (open !== 0 || close !== raw.length - 1) {
+        throw new Error(`[ress] "${sourceFile}" tiene corchetes desbalanceados o mezclados con texto en "${raw}". ` +
+            'Un segmento con parámetro se escribe entero entre corchetes: [id], [...slug], [[...slug]].');
+    }
+    const inner = raw.slice(1, -1);
+    // `[[...slug]]` — el doble corchete lo vuelve opcional.
+    if (inner.startsWith('[') && inner.endsWith(']')) {
+        const name = requireName(inner.slice(1, -1).replace(/^\.\.\./, ''), raw, sourceFile);
+        if (!inner.slice(1, -1).startsWith('...')) {
+            throw new Error(`[ress] "${sourceFile}" escribe "${raw}" con doble corchete pero sin "...". ` +
+                'El doble corchete es para un catch-all opcional: [[...slug]].');
+        }
+        return { kind: 'optionalCatchAll', value: name };
+    }
+    if (inner.startsWith('...')) {
+        return { kind: 'catchAll', value: requireName(inner.slice(3), raw, sourceFile) };
+    }
+    return { kind: 'dynamic', value: requireName(inner, raw, sourceFile) };
+}
+function requireName(name, raw, sourceFile) {
+    if (!name) {
+        throw new Error(`[ress] "${sourceFile}" declara el parámetro "${raw}" sin nombre. ` +
+            'Sin nombre no hay forma de leer su valor desde la página.');
+    }
+    return name;
+}
+function toPattern(segments) {
+    if (segments.length === 0)
+        return '/';
+    return ('/' +
+        segments
+            .map((s) => {
+            if (s.kind === 'static')
+                return s.value;
+            if (s.kind === 'dynamic')
+                return `[${s.value}]`;
+            if (s.kind === 'catchAll')
+                return `[...${s.value}]`;
+            return `[[...${s.value}]]`;
+        })
+            .join('/'));
+}
+/**
+ * Identificador estable de una página.
+ *
+ * Es la misma clave que usa el catálogo de variantes de F-016, para que las dos
+ * estructuras hablen del mismo objeto sin traducir nada entre ellas.
+ */
+function pageIdFromFile(sourceFile, pagesDir = 'app/pages') {
+    return stripPagesDir(sourceFile, pagesDir)
+        .replace(EXTENSION, '')
+        .replace(/\//g, '__')
+        .replace(/\[([^\]]+)\]/g, '_$1_');
+}
+/** Qué clase de entrada es, según dónde vive el archivo. */
+function classifyEntry(sourceFile, pagesDir = 'app/pages') {
+    const relative = stripPagesDir(sourceFile, pagesDir);
+    if (relative.startsWith('api/'))
+        return 'api';
+    if (/(^|\/)_error(\.|\/)|(^|\/)error\//.test(relative))
+        return 'error';
+    return 'page';
+}
+function stripPagesDir(sourceFile, pagesDir) {
+    const normalized = sourceFile.replace(/\\/g, '/');
+    const marker = pagesDir.replace(/\\/g, '/').replace(/\/$/, '') + '/';
+    const index = normalized.indexOf(marker);
+    return index === -1 ? normalized.replace(/^\//, '') : normalized.slice(index + marker.length);
+}

package/dist/routes/rank.d.ts

@@ -0,0 +1,12 @@
+import type { RouteEntry, RouteSegment } from './types';
+/** Clave de comparación de una ruta: la especificidad de cada segmento, en orden. */
+export declare function computeRank(segments: readonly RouteSegment[]): number[];
+/**
+ * Orden en que se prueban las rutas.
+ *
+ * Se compara segmento a segmento; el primero que difiere decide. A igual
+ * especificidad gana la más larga —describe más de la URL— y, si aún empatan, el
+ * orden alfabético del patrón, para que el resultado no dependa de en qué orden
+ * el sistema de archivos devolvió los nombres.
+ */
+export declare function compareEntries(a: RouteEntry, b: RouteEntry): number;

package/dist/routes/rank.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeRank = computeRank;
+exports.compareEntries = compareEntries;
+/**
+ * Cuán específico es cada tipo de segmento. Menor gana.
+ *
+ * Un literal describe una sola URL; un parámetro, todas las de su posición; un
+ * catch-all, todas las que empiecen igual. Ordenar por esto es lo que hace que
+ * `/users/nuevo` gane sobre `/users/[id]` sin que nadie declare la prioridad.
+ */
+const KIND_RANK = {
+    static: 0,
+    dynamic: 1,
+    catchAll: 2,
+    optionalCatchAll: 3,
+};
+/** Clave de comparación de una ruta: la especificidad de cada segmento, en orden. */
+function computeRank(segments) {
+    return segments.map((s) => KIND_RANK[s.kind]);
+}
+/**
+ * Orden en que se prueban las rutas.
+ *
+ * Se compara segmento a segmento; el primero que difiere decide. A igual
+ * especificidad gana la más larga —describe más de la URL— y, si aún empatan, el
+ * orden alfabético del patrón, para que el resultado no dependa de en qué orden
+ * el sistema de archivos devolvió los nombres.
+ */
+function compareEntries(a, b) {
+    const length = Math.min(a.rank.length, b.rank.length);
+    for (let i = 0; i < length; i++) {
+        if (a.rank[i] !== b.rank[i])
+            return a.rank[i] - b.rank[i];
+    }
+    if (a.rank.length !== b.rank.length) {
+        const [corta, larga] = a.rank.length < b.rank.length ? [a, b] : [b, a];
+        const extra = larga.rank[corta.rank.length];
+        // Un catch-all opcional puede no consumir nada, así que la ruta que lo lleva
+        // atiende también todo lo que atiende la corta: es la más general de las dos.
+        // Sin esto, `/users/[id]/[[...rest]]` se probaría antes que `/users/[id]` y
+        // esta última quedaría inalcanzable.
+        if (extra === KIND_RANK.optionalCatchAll)
+            return corta === a ? -1 : 1;
+        // En cualquier otro caso, la más larga describe más de la URL.
+        return b.rank.length - a.rank.length;
+    }
+    return a.pattern.localeCompare(b.pattern);
+}

package/dist/routes/router.d.ts

@@ -0,0 +1,44 @@
+import { Router, type RequestHandler } from 'express';
+import type { ModuleLoader } from '../runtime/module-loader';
+import type { RouteEntry, RouteManifest } from './types';
+export interface ChainContext {
+    moduleLoader?: ModuleLoader;
+    renderOptions: {
+        enablePlatformDetection: boolean;
+        renderFunction?: (options: {
+            url: string;
+            platform: string;
+            req: any;
+        }) => Promise<string>;
+        viteConfig: unknown;
+        security: unknown;
+    };
+}
+/**
+ * La cadena de middlewares de una entrada.
+ *
+ * Es el cuerpo que estaba duplicado entre los dos constructores de router del
+ * modelo anterior: lo que hace un middleware de carpeta, `getServerSideProps` y
+ * el render, en ese orden. Tenerlo una vez es lo que garantiza que los dos
+ * caminos se comporten igual.
+ */
+export declare function buildChain(entry: RouteEntry, ctx: ChainContext): Promise<RequestHandler[]>;
+export interface RessRouterState {
+    manifest: RouteManifest;
+    chains: Map<string, RequestHandler[]>;
+}
+/**
+ * Construye el estado de ruteo: el manifest más la cadena de cada entrada.
+ *
+ * Se arma entero y se devuelve entero, de modo que reemplazarlo en desarrollo
+ * sea una sola asignación y ninguna petición vea una mezcla de dos versiones.
+ */
+export declare function buildRouterState(manifest: RouteManifest, ctx: ChainContext): Promise<RessRouterState>;
+/**
+ * El router de páginas.
+ *
+ * Un solo despachador para todas las rutas y un solo manejador de errores, que
+ * sabe qué ruta falló porque el despachador lo dejó en la petición. El modelo
+ * anterior registraba un manejador por página.
+ */
+export declare function createPageRouter(getState: () => RessRouterState, ctx: ChainContext): Router;

package/dist/routes/router.js

@@ -0,0 +1,81 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildChain = buildChain;
+exports.buildRouterState = buildRouterState;
+exports.createPageRouter = createPageRouter;
+const express_1 = require("express");
+const middlewares_1 = require("../helpers/middlewares");
+const render_1 = require("../render");
+const dispatcher_1 = require("./dispatcher");
+/**
+ * La cadena de middlewares de una entrada.
+ *
+ * Es el cuerpo que estaba duplicado entre los dos constructores de router del
+ * modelo anterior: lo que hace un middleware de carpeta, `getServerSideProps` y
+ * el render, en ese orden. Tenerlo una vez es lo que garantiza que los dos
+ * caminos se comporten igual.
+ */
+async function buildChain(entry, ctx) {
+    return [
+        // Express reasigna `req.params` cada vez que la petición entra a un router
+        // anidado, así que los valores que extrajo el despachador se restauran acá,
+        // ya dentro de la cadena de la página.
+        (req, _res, next) => {
+            if (req.ressParams)
+                req.params = req.ressParams;
+            next();
+        },
+        // Se busca por la ubicación del archivo y no por el patrón: un grupo no
+        // aparece en la URL, así que `app/pages/(marketing)/about.tsx` tiene patrón
+        // `/about` y sus middlewares viven en `/(marketing)`. Compararlos daría
+        // siempre falso y la carpeta quedaría sin proteger.
+        ...(await (0, middlewares_1.loadPageMiddlewares)(middlewareRouteOf(entry), ctx.moduleLoader)),
+        await (0, middlewares_1.getServerSidePropsAsMiddleware)(entry.sourceFile, ctx.moduleLoader),
+        (0, render_1.createRenderMiddleware)({ route: entry.pattern, file: entry.sourceFile, pageId: entry.pageId }, ctx.renderOptions),
+    ];
+}
+/**
+ * La ruta con la que se buscan los middlewares de una entrada: la que describe
+ * dónde vive el archivo, con los grupos incluidos.
+ */
+function middlewareRouteOf(entry) {
+    const relative = entry.sourceFile
+        .replace(/\\/g, '/')
+        .replace(/^.*app\/pages\//, '')
+        .replace(/\.[^./]+$/, '')
+        .replace(/\/?index$/, '');
+    return '/' + relative;
+}
+/**
+ * Construye el estado de ruteo: el manifest más la cadena de cada entrada.
+ *
+ * Se arma entero y se devuelve entero, de modo que reemplazarlo en desarrollo
+ * sea una sola asignación y ninguna petición vea una mezcla de dos versiones.
+ */
+async function buildRouterState(manifest, ctx) {
+    const chains = new Map();
+    for (const entry of manifest.entries) {
+        if (entry.kind === 'api')
+            continue;
+        chains.set(entry.pageId, await buildChain(entry, ctx));
+    }
+    return { manifest, chains };
+}
+/**
+ * El router de páginas.
+ *
+ * Un solo despachador para todas las rutas y un solo manejador de errores, que
+ * sabe qué ruta falló porque el despachador lo dejó en la petición. El modelo
+ * anterior registraba un manejador por página.
+ */
+function createPageRouter(getState, ctx) {
+    const router = (0, express_1.Router)();
+    router.use((0, dispatcher_1.createDispatcher)(getState));
+    router.use((err, req, res, next) => {
+        const entry = req.ressRoute;
+        if (!entry)
+            return next(err);
+        return (0, middlewares_1.createPageErrorHandler)(entry.sourceFile, ctx.moduleLoader)(err, req, res, next);
+    });
+    return router;
+}

package/dist/routes/scan.d.ts

@@ -0,0 +1,16 @@
+import { type RouteManifestData } from './types';
+export interface ScanOptions {
+    pagesDir?: string;
+    /**
+     * Un conflicto en build detiene el proceso; en desarrollo avisa y sigue, para
+     * no dejar el servidor caído mientras alguien renombra un archivo.
+     */
+    strict?: boolean;
+}
+/**
+ * Qué rutas existen en el proyecto.
+ *
+ * Lee el sistema de archivos **una vez**. El modelo anterior lo globeaba en cada
+ * arranque, también en producción, donde el árbol ya no puede cambiar.
+ */
+export declare function scanRoutes(options?: ScanOptions): Promise<RouteManifestData>;

package/dist/routes/scan.js

@@ -0,0 +1,82 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.scanRoutes = scanRoutes;
+const node_path_1 = __importDefault(require("node:path"));
+const fast_glob_1 = __importDefault(require("fast-glob"));
+const module_extensions_1 = require("../fs/module-extensions");
+const parse_1 = require("./parse");
+const rank_1 = require("./rank");
+const rank_2 = require("./rank");
+const types_1 = require("./types");
+/**
+ * Archivos que viven junto a las páginas pero no son rutas.
+ *
+ * `middlewares.ts` declara la cadena de su carpeta y `algo.middlewares.ts` la de
+ * su página; ninguno se navega. Los que empiezan con `_` son la convención para
+ * lo que acompaña a una página sin ser una.
+ */
+const NOT_A_ROUTE = /(^|\/)middlewares\.[^.]+$|\.(middlewares|test|spec|d)\.[^.]+$|(^|\/)_/;
+/**
+ * Qué rutas existen en el proyecto.
+ *
+ * Lee el sistema de archivos **una vez**. El modelo anterior lo globeaba en cada
+ * arranque, también en producción, donde el árbol ya no puede cambiar.
+ */
+async function scanRoutes(options = {}) {
+    const pagesDir = options.pagesDir ?? 'app/pages';
+    // Qué extensiones cuentan lo declara la política del proyecto, no este archivo.
+    const files = await (0, fast_glob_1.default)((0, module_extensions_1.pageGlob)((0, module_extensions_1.getExtensionPolicy)(), pagesDir), { absolute: false });
+    const entries = [];
+    const byPattern = new Map();
+    const conflicts = [];
+    const manifestRoot = node_path_1.default.resolve(node_path_1.default.dirname(node_path_1.default.resolve(pagesDir)), '..');
+    for (const file of files.sort()) {
+        // fast-glob devuelve separadores nativos en Windows; el parser de rutas y
+        // los identificadores del catálogo usan `/` para que el resultado sea
+        // idéntico en todos los sistemas.
+        const normalizedFile = file.replace(/\\/g, '/');
+        const sourceFile = node_path_1.default.isAbsolute(pagesDir)
+            ? node_path_1.default.relative(manifestRoot, normalizedFile).replace(/\\/g, '/')
+            : normalizedFile;
+        // Se evalúa sobre el path relativo entero: una carpeta `_lib/` no es una
+        // ruta, igual que no lo es un archivo `_helper.tsx`.
+        const normalizedPagesDir = pagesDir.replace(/\\/g, '/');
+        const relative = normalizedFile.slice(normalizedFile.indexOf(normalizedPagesDir) + normalizedPagesDir.length + 1);
+        if (NOT_A_ROUTE.test('/' + relative))
+            continue;
+        const parsed = (0, parse_1.parseRoutePattern)(normalizedFile, normalizedPagesDir);
+        const entry = {
+            pageId: (0, parse_1.pageIdFromFile)(normalizedFile, normalizedPagesDir),
+            pattern: parsed.pattern,
+            segments: parsed.segments,
+            kind: (0, parse_1.classifyEntry)(normalizedFile, normalizedPagesDir),
+            sourceFile,
+            paramNames: parsed.paramNames,
+            groups: parsed.groups,
+            rank: (0, rank_1.computeRank)(parsed.segments),
+            server: { devId: '/' + sourceFile },
+        };
+        // Dos archivos que producen la misma URL son ambiguos: cuál gana dependería
+        // del orden en que el sistema de archivos los devolvió.
+        const clash = byPattern.get(`${entry.kind} ${entry.pattern}`);
+        if (clash) {
+            const message = `[ress] "${clash.sourceFile}" y "${file}" producen la misma ruta "${entry.pattern}". ` +
+                'Renombrá uno de los dos.';
+            if (options.strict)
+                throw new Error(message);
+            console.warn(`${message}\nPor ahora responde "${clash.sourceFile}".`);
+            conflicts.push({ pattern: entry.pattern, files: [clash.sourceFile, file] });
+            continue;
+        }
+        byPattern.set(`${entry.kind} ${entry.pattern}`, entry);
+        entries.push(entry);
+    }
+    return {
+        version: types_1.ROUTE_MANIFEST_VERSION,
+        entries: entries.sort(rank_2.compareEntries),
+        ...(conflicts.length ? { conflicts } : {}),
+    };
+}

package/dist/routes/types.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Qué rutas existen y cuál atiende cada URL.
+ *
+ * El modelo anterior derivaba la ruta del archivo en cada arranque, globeando el
+ * sistema de archivos también en producción, y traducía el patrón a una cadena
+ * de Express que no podía expresar ni catch-all ni grupos. Acá el conjunto de
+ * rutas es un dato: se calcula una vez, se serializa en el build y se carga.
+ */
+export type SegmentKind = 'static' | 'dynamic' | 'catchAll' | 'optionalCatchAll';
+export interface RouteSegment {
+    kind: SegmentKind;
+    /** Literal de URL para `static`; nombre del parámetro para el resto. */
+    value: string;
+}
+/** Qué es una entrada. Determina si participa del matcheo de navegación. */
+export type RouteEntryKind = 'page' | 'error' | 'api';
+/** Identificador estable de una página. La misma clave que usa el catálogo de variantes. */
+export type PageId = string;
+export interface ServerModuleRef {
+    /** Identificador que entiende el cargador de módulos en desarrollo. */
+    devId: string;
+    /**
+     * Chunk compilado, relativo a la raíz de salida del build de servidor. Lo
+     * completa el build; en desarrollo no existe.
+     */
+    buildChunk?: string;
+}
+export interface RouteEntry {
+    pageId: PageId;
+    /** Patrón canónico con notación de archivos. Ej: `/users/[id]`. */
+    pattern: string;
+    segments: RouteSegment[];
+    kind: RouteEntryKind;
+    /** Archivo fuente, relativo a la raíz del proyecto. */
+    sourceFile: string;
+    /** Nombres de parámetro, en orden de aparición. */
+    paramNames: string[];
+    /** Grupos atravesados. Informativo: no afectan la URL. */
+    groups: string[];
+    /** Clave de precedencia precalculada. */
+    rank: number[];
+    server: ServerModuleRef;
+    /** Sólo para `error`: qué código de estado atiende. */
+    statusCode?: number;
+    /** Sólo para `api`: métodos declarados. Ausente significa todos. */
+    methods?: string[];
+}
+export interface RouteMatch {
+    entry: RouteEntry;
+    params: Record<string, string | string[]>;
+}
+export interface MatchOptions {
+    /** Qué clases de entrada participan. Por defecto sólo `page`. */
+    kinds?: readonly RouteEntryKind[];
+}
+/** Dos archivos que compiten por el mismo patrón, detectados al escanear. */
+export interface RouteConflict {
+    pattern: string;
+    files: string[];
+}
+/** Lo que se serializa al disco. */
+export interface RouteManifestData {
+    /** Sube cuando el formato cambia de forma incompatible. */
+    version: number;
+    entries: RouteEntry[];
+    /**
+     * Conflictos detectados en modo no estricto (desarrollo).
+     *
+     * En modo estricto (`build`) `scanRoutes` lanza en vez de completar esta
+     * lista: un build no deja artefactos parciales publicables. F-033 (`ress
+     * info`) es quien la consume para diagnosticar sin abortar.
+     */
+    conflicts?: RouteConflict[];
+}
+export interface RouteManifest {
+    readonly entries: readonly RouteEntry[];
+    /** Qué entrada atiende esta URL. `undefined` si ninguna. */
+    match(pathname: string, options?: MatchOptions): RouteMatch | undefined;
+    /** Una entrada por su identificador. */
+    get(pageId: PageId): RouteEntry | undefined;
+    /** Las entradas de una clase, en orden de precedencia. */
+    byKind(kind: RouteEntryKind): readonly RouteEntry[];
+}
+/** Sube cuando el formato del manifest cambia de forma incompatible. */
+export declare const ROUTE_MANIFEST_VERSION = 1;

package/dist/routes/types.js

@@ -0,0 +1,13 @@
+"use strict";
+/**
+ * Qué rutas existen y cuál atiende cada URL.
+ *
+ * El modelo anterior derivaba la ruta del archivo en cada arranque, globeando el
+ * sistema de archivos también en producción, y traducía el patrón a una cadena
+ * de Express que no podía expresar ni catch-all ni grupos. Acá el conjunto de
+ * rutas es un dato: se calcula una vez, se serializa en el build y se carga.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ROUTE_MANIFEST_VERSION = void 0;
+/** Sube cuando el formato del manifest cambia de forma incompatible. */
+exports.ROUTE_MANIFEST_VERSION = 1;

package/dist/runtime/dev-server.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Runtime de desarrollo.
+ *
+ * Crea el servidor de Vite, resuelve el entorno de servidor y construye el cargador de
+ * módulos una sola vez, que es el que usa el resto del framework.
+ */
+import { type FetchableEnvironment, type ModuleLoader } from './module-loader';
+import type { AssetIndex, VariantCatalog } from '../variants/types';
+import type { RouteManifest } from '../routes/types';
+export interface RessRuntime {
+    /** Instancia de Vite. `null` en producción. */
+    vite: any | null;
+    /** Carga módulos de usuario. Único en dev y prod. */
+    moduleLoader: ModuleLoader;
+    templateHtml: string;
+    isProduction: boolean;
+    /** Qué variantes tiene cada página. Se arma una vez al arrancar. */
+    catalog: VariantCatalog;
+    /** Qué rutas existen y cuál atiende cada URL. */
+    routes: RouteManifest;
+    /** Artefactos por página y variante. */
+    assets: AssetIndex;
+    /** Archivos que emitió el build de cliente. Vacío en desarrollo. */
+    buildOutputs: ReadonlySet<string>;
+    /**
+     * Registra un aviso de cambio en el código de usuario. Devuelve la función
+     * para dejar de escuchar. En producción no se invoca nunca.
+     */
+    onSourceChange(cb: (file: string) => void): () => void;
+    close(): Promise<void>;
+}
+/**
+ * Elige el entorno desde el que se cargarán los módulos de usuario.
+ *
+ * Se prefiere `ssr` por nombre; si un proyecto declaró otros entornos, se cae al
+ * primero disponible en vez de fallar. Nunca se asume que el entorno sea del
+ * tipo ejecutable: el cargador se construye sobre `fetchModule()`, presente en
+ * todos los tipos.
+ */
+export declare function resolveSsrEnvironment(server: any): FetchableEnvironment;
+export interface DevRuntimeOptions {
+    /**
+     * Plugins de Vite a aplicar, además de los que el proyecto declare en su
+     * propio `vite.config.*` si lo tiene.
+     *
+     * F-033 (la CLI) los necesita: un proyecto sin `vite.config.ts` no tiene
+     * quién le pase `ressPlugin()` a Vite si `createDevRuntime` no acepta
+     * plugins inline. Antes de esta opción, `createServer` dependía por completo
+     * de que Vite encontrara un archivo de configuración en el directorio de
+     * trabajo — que es justamente lo que la CLI existe para volver innecesario.
+     */
+    plugins?: unknown[];
+}
+export declare function createDevRuntime(base?: string, 
+/**
+ * Prefijo con el que se emiten las URL de artefactos.
+ *
+ * Va aparte del `base` de Vite porque el prefijo de ruta lo administra el
+ * framework: el pipeline de petición lo quita antes de que Vite vea la URL, así
+ * que Vite sigue viviendo en `/` y sólo lo que se escribe en el HTML lo lleva.
+ */
+assetPrefix?: string, options?: DevRuntimeOptions): Promise<RessRuntime>;

package/dist/runtime/dev-server.js

@@ -0,0 +1,94 @@
+"use strict";
+/**
+ * Runtime de desarrollo.
+ *
+ * Crea el servidor de Vite, resuelve el entorno de servidor y construye el cargador de
+ * módulos una sola vez, que es el que usa el resto del framework.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveSsrEnvironment = resolveSsrEnvironment;
+exports.createDevRuntime = createDevRuntime;
+const module_loader_1 = require("./module-loader");
+const assets_1 = require("../variants/assets");
+const manifest_1 = require("../routes/manifest");
+const scan_1 = require("../routes/scan");
+const index_1 = require("../plugin/index");
+const template_1 = require("./template");
+/**
+ * Elige el entorno desde el que se cargarán los módulos de usuario.
+ *
+ * Se prefiere `ssr` por nombre; si un proyecto declaró otros entornos, se cae al
+ * primero disponible en vez de fallar. Nunca se asume que el entorno sea del
+ * tipo ejecutable: el cargador se construye sobre `fetchModule()`, presente en
+ * todos los tipos.
+ */
+function resolveSsrEnvironment(server) {
+    const envs = server?.environments;
+    if (!envs) {
+        throw new Error('[ress] El servidor de Vite no expone environments. ' +
+            'ress.js requiere Vite 8 o superior.');
+    }
+    const env = envs.ssr ?? Object.values(envs)[0];
+    if (!env || typeof env.fetchModule !== 'function') {
+        throw new Error('[ress] No se encontró un entorno de servidor utilizable. ' +
+            `Entornos disponibles: ${Object.keys(envs).join(', ') || '(ninguno)'}`);
+    }
+    return env;
+}
+async function createDevRuntime(base = '/', 
+/**
+ * Prefijo con el que se emiten las URL de artefactos.
+ *
+ * Va aparte del `base` de Vite porque el prefijo de ruta lo administra el
+ * framework: el pipeline de petición lo quita antes de que Vite vea la URL, así
+ * que Vite sigue viviendo en `/` y sólo lo que se escribe en el HTML lo lleva.
+ */
+assetPrefix = base, options = {}) {
+    const { createServer } = await import('vite');
+    const vite = await createServer({
+        server: { middlewareMode: true },
+        appType: 'custom',
+        base,
+        plugins: options.plugins,
+    });
+    const env = resolveSsrEnvironment(vite);
+    const moduleLoader = await (0, module_loader_1.createDevModuleLoader)(env);
+    // El runner mantiene su propia caché de módulos evaluados y corre sin canal de
+    // HMR, así que nada la descarta por su cuenta. Conectar el watcher es lo que
+    // hace que editar una página o un middleware se refleje en la siguiente
+    // petición en vez de exigir reiniciar el servidor.
+    const listeners = new Set();
+    const onFileChange = (file) => {
+        moduleLoader.invalidate(file);
+        for (const cb of listeners)
+            cb(file);
+    };
+    vite.watcher.on('change', onFileChange);
+    vite.watcher.on('unlink', onFileChange);
+    const templateHtml = await (0, template_1.readTemplateHtml)();
+    // El plugin lo arma al resolver la configuración; si por algún motivo no
+    // corrió, se arma acá para no dejar el runtime sin catálogo.
+    const catalog = (0, index_1.getVariantCatalog)() ?? (await (0, index_1.refreshVariantCatalog)());
+    const routes = (0, manifest_1.createRouteManifest)(await (0, scan_1.scanRoutes)());
+    return {
+        vite,
+        moduleLoader,
+        templateHtml,
+        isProduction: false,
+        catalog,
+        routes,
+        assets: (0, assets_1.createDevAssetIndex)(catalog, assetPrefix),
+        // En desarrollo los sirve Vite, no el middleware de estáticos.
+        buildOutputs: new Set(),
+        onSourceChange: (cb) => {
+            listeners.add(cb);
+            return () => listeners.delete(cb);
+        },
+        close: async () => {
+            vite.watcher.off('change', onFileChange);
+            vite.watcher.off('unlink', onFileChange);
+            await moduleLoader.close();
+            await vite.close();
+        },
+    };
+}