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

package/dist/router.js

@@ -1,161 +1,162 @@
 "use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getPages = void 0;
-exports.createAutoViteServer = createAutoViteServer;
+exports.waitForViteRouter = waitForViteRouter;
 exports.createViteRouter = createViteRouter;
-exports.listDetectedPages = listDetectedPages;
 const express_1 = require("express");
-const pages_1 = require("./pages");
-const express_2 = __importDefault(require("express"));
-const vite_config_1 = require("./helpers/vite-config");
-const middlewares_1 = require("./helpers/middlewares");
-const render_1 = require("./render");
-async function createAutoViteServer(options = {}) {
-    const { port = 5173, base = '/', enablePlatformDetection = true } = options;
-    const isProduction = process.env.NODE_ENV === 'production';
-    const app = (0, express_2.default)();
-    const viteConfig = await (0, vite_config_1.setupVite)(isProduction, base);
-    if (!isProduction) {
-        app.use(viteConfig.vite.middlewares);
-        app.use('/dist/.entries', express_2.default.static('dist/.entries'));
-    }
-    else {
-        const prodFactory = (0, vite_config_1.createProdMiddleware)();
-        const prodMiddleware = await prodFactory();
-        app.use(prodMiddleware);
-    }
-    const viteRouter = createViteRouter({
-        enablePlatformDetection,
-        vite: viteConfig.vite,
-        templateHtml: viteConfig.templateHtml,
-        isProduction
-    });
-    app.use('/', viteRouter);
-    app.use(express_2.default.static('public'));
-    const start = () => {
-        return app.listen(port, () => {
-            if (process.env.NODE_ENV !== 'production') {
-                const pages = (0, pages_1.getPages)();
-                console.log(`🚀 Auto Vite Server started at http://localhost:${port}`);
-                console.log(`📄 Auto-detected routes:`);
-                pages.forEach(page => {
-                    const expressDisplay = page.route !== page.expressRoute ? ` (Express: ${page.expressRoute})` : '';
-                    console.log(`   ${page.route}${expressDisplay} -> ${page.file}`);
-                });
-            }
-        });
-    };
-    return { app, vite: viteConfig.vite, start };
+const prod_server_1 = require("./runtime/prod-server");
+const security_1 = require("./security");
+const router_1 = require("./routes/router");
+const manifest_1 = require("./routes/manifest");
+const scan_1 = require("./routes/scan");
+const config_1 = require("./config");
+const routerReadiness = new WeakMap();
+/** Espera a que el runtime, el manifest y las cadenas de middleware estén listos. */
+function waitForViteRouter(router) {
+    return routerReadiness.get(router) ?? Promise.resolve();
 }
+/**
+ * El router de ress.js.
+ *
+ * Antes había dos constructores con el 90 % del cuerpo repetido, uno para quien
+ * deja que el framework arme el runtime y otro para quien lo aporta. La
+ * diferencia real entre los dos es de dónde sale el runtime, así que eso es lo
+ * único que se decide acá; el resto del camino es uno solo.
+ */
 function createViteRouter(options = {}) {
-    const needsAutoConfig = !options.vite && !options.templateHtml && options.isProduction !== true;
-    if (needsAutoConfig) {
-        return createAutoRouter(options);
-    }
-    return createManualRouter(options);
-}
-function createAutoRouter(options) {
     const { renderFunction, enablePlatformDetection = true } = options;
-    const isProduction = process.env.NODE_ENV === 'production';
-    let viteConfig = null;
-    let initialized = false;
+    const security = options.security ?? (0, security_1.resolveSecurityOptions)(options.securityOptions);
+    const providesOwnRuntime = Boolean(options.moduleLoader || options.templateHtml);
+    const isProduction = options.isProduction ?? process.env.NODE_ENV === 'production';
     const mainRouter = (0, express_1.Router)();
-    const initializeIfNeeded = async () => {
-        if (initialized)
-            return viteConfig;
-        const basePath = process.env.BASE || '/';
-        viteConfig = await (0, vite_config_1.setupVite)(isProduction, basePath);
-        if (!isProduction) {
-            mainRouter.use(viteConfig.vite.middlewares);
+    let runtime = null;
+    /**
+     * El manifest vigente.
+     *
+     * Se guarda acá y no se lee del runtime en cada rearmado: en desarrollo hay
+     * que volver a escanear cuando aparece o desaparece un archivo, y el runtime
+     * lo construyó una sola vez al arrancar.
+     */
+    let routes = null;
+    let state = null;
+    let pageRouter = null;
+    let assetMiddleware = null;
+    let configMiddleware = null;
+    let stale = false;
+    let rescan = false;
+    const markRescan = () => {
+        stale = true;
+        rescan = true;
+    };
+    const chainContext = () => ({
+        moduleLoader: runtime?.moduleLoader,
+        renderOptions: {
+            enablePlatformDetection,
+            renderFunction,
+            security,
+            viteConfig: () => runtime,
+        },
+    });
+    const rebuild = async (rescan = false) => {
+        stale = false;
+        if (rescan || !routes)
+            routes = (0, manifest_1.createRouteManifest)(await (0, scan_1.scanRoutes)());
+        state = await (0, router_1.buildRouterState)(routes, chainContext());
+    };
+    const setup = async () => {
+        // La configuración primero: de ella salen el prefijo de ruta, el prefijo de
+        // artefactos y las reglas del pipeline, y las tres se necesitan antes de
+        // armar el runtime.
+        const config = options.config ??
+            (await (0, config_1.loadConfig)(options.root ?? process.cwd(), options.mode ?? (isProduction ? 'production' : 'development')));
+        configMiddleware = (0, config_1.createConfigMiddleware)(config);
+        const assetPrefix = (0, config_1.assetPrefixFor)({
+            basePath: config.basePath,
+            cdnPrefix: config.assets?.cdnPrefix,
+        });
+        if (options.runtime) {
+            runtime = options.runtime;
+            routes = runtime.routes;
+            assetMiddleware = isProduction
+                ? await (0, prod_server_1.createProdAssetMiddleware)(undefined, { buildOutputs: runtime.buildOutputs })
+                : runtime.vite.middlewares;
         }
-        else {
-            const prodFactory = (0, vite_config_1.createProdMiddleware)();
-            const prodMiddleware = await prodFactory();
-            mainRouter.use(prodMiddleware);
+        else if (providesOwnRuntime) {
+            // Quien aporta su propio cargador de módulos no tiene runtime del
+            // framework, así que se arma uno mínimo con lo que declaró.
+            runtime = {
+                vite: null,
+                moduleLoader: options.moduleLoader,
+                templateHtml: options.templateHtml ?? '',
+                isProduction,
+                buildOutputs: new Set(),
+                close: async () => { },
+            };
         }
-        initialized = true;
-        return viteConfig;
-    };
-    const pages = (0, pages_1.getPages)();
-    // Initialize Vite ONCE before setting up any routes
-    const setupRoutes = async () => {
-        if (!viteConfig)
-            await initializeIfNeeded();
-        // Process pages sequentially to avoid race conditions
-        for (const page of pages) {
-            // Dynamic middleware loading for HMR support
-            const HMRMiddleware = await (0, middlewares_1.createDynamicPageMiddlewares)(page.route, page.file, viteConfig?.vite);
-            // Productive middlewares
-            const prevMiddlewares = await (0, middlewares_1.loadPageMiddlewares)(page.route, viteConfig?.vite);
-            const serverSidePropsMiddleware = await (0, middlewares_1.getServerSidePropsAsMiddleware)(page.file, viteConfig?.vite);
-            const renderMiddleware = (0, render_1.createRenderMiddleware)(page, {
-                enablePlatformDetection,
-                renderFunction,
-                viteConfig: () => viteConfig // pasar por función para evitar capturar null
-            });
-            const pageMiddlewares = isProduction ? [
-                ...prevMiddlewares,
-                serverSidePropsMiddleware,
-                renderMiddleware
-            ] : [
-                HMRMiddleware,
-                renderMiddleware
-            ];
-            mainRouter.get(page.expressRoute, ...pageMiddlewares);
-            // Error middleware separado
-            mainRouter.use(page.expressRoute, (0, middlewares_1.createPageErrorHandler)(page.file, viteConfig?.vite));
+        else {
+            // El `base` de Vite se queda en `/`: el prefijo de ruta lo quita el
+            // pipeline de petición, y lo que se escribe en el HTML lo lleva por el
+            // prefijo de artefactos.
+            runtime = await (0, prod_server_1.createRuntime)(isProduction, options.basePath ?? process.env.BASE ?? '/', assetPrefix);
+            routes = runtime.routes;
+            // Los estáticos se atienden antes que las páginas: un pedido de artefacto
+            // no tiene que recorrer el manifest de rutas, y una ruta que capture todo
+            // no debe interceptarlos.
+            assetMiddleware = isProduction
+                ? await (0, prod_server_1.createProdAssetMiddleware)(undefined, { buildOutputs: runtime.buildOutputs })
+                : runtime.vite.middlewares;
         }
+        await rebuild();
+        pageRouter = (0, router_1.createPageRouter)(() => state, chainContext());
+        // Se marca y se rearma en la petición siguiente, no acá: el watcher avisa
+        // antes de que Vite termine de invalidar su grafo, y rearmar en ese instante
+        // volvería a leer la versión anterior del archivo.
+        runtime.onSourceChange?.(() => {
+            stale = true;
+        });
+        // Crear o borrar una página cambia el conjunto de rutas, no sólo el
+        // contenido de un módulo: hay que volver a escanear.
+        runtime.vite?.watcher?.on('add', markRescan);
+        runtime.vite?.watcher?.on('unlink', markRescan);
     };
-    // Setup routes asynchronously but don't block router creation
-    setupRoutes().catch(console.error);
+    // El armado es asíncrono y una petición puede llegar antes de que termine. Se
+    // espera la promesa en vez de responder como si la ruta no existiera.
+    const ready = setup();
+    routerReadiness.set(mainRouter, ready);
+    mainRouter.use((req, res, next) => {
+        ready.then(() => {
+            const serve = () => {
+                // Se lee acá y no antes: la marca la pone el pipeline de configuración,
+                // que corre después de este callback.
+                const outside = req.ressOutsideBasePath === true;
+                // Después de la configuración, los artefactos: un pedido de artefacto no
+                // tiene que recorrer el manifest de rutas. Se registra acá y no con
+                // `use()` porque los dos middlewares se resuelven dentro del armado
+                // asíncrono, y registrarlos después dejaría al despachador por delante.
+                // Fuera del prefijo no hay páginas: declarar un prefijo y seguir
+                // sirviendo el sitio entero por la raíz es exactamente lo que un prefijo
+                // existe para evitar. Los artefactos sí se intentan igual, porque las
+                // rutas internas del servidor de desarrollo de Vite —`/@vite/client`,
+                // `/@fs/`— viven en la raíz y no bajo el prefijo de la aplicación.
+                const after = (err) => err ? next(err) : outside ? next() : dispatch(req, res, next);
+                if (!assetMiddleware)
+                    return after();
+                assetMiddleware(req, res, after);
+            };
+            // Barra final, prefijo de ruta, redirecciones y reescrituras: todo lo que
+            // decide *qué* URL se está atendiendo va antes que quien la atiende.
+            if (!configMiddleware)
+                return serve();
+            configMiddleware(req, res, ((err) => (err ? next(err) : serve())));
+        }, next);
+    });
+    function dispatch(req, res, next) {
+        const run = () => (pageRouter ? pageRouter(req, res, next) : next());
+        if (!stale)
+            return run();
+        rebuild(rescan).then(() => { rescan = false; run(); }, next);
+    }
     return mainRouter;
 }
-function createManualRouter(options) {
-    const { vite, renderFunction, enablePlatformDetection = true } = options;
-    const router = (0, express_1.Router)();
-    const pages = (0, pages_1.getPages)();
-    // Crear viteConfig para processRequest
-    const viteConfig = {
-        vite,
-        templateHtml: options.templateHtml || '',
-        isProduction: options.isProduction || false,
-        manifest: null
-    };
-    // Process pages sequentially to avoid race conditions
-    const setupRoutes = async () => {
-        for (const page of pages) {
-            // Dynamic middleware loading for HMR support(only in dev)
-            const HMRMiddleware = await (0, middlewares_1.createDynamicPageMiddlewares)(page.route, page.file, vite);
-            // Productive middlewares
-            const prevMiddlewares = await (0, middlewares_1.loadPageMiddlewares)(page.route, vite);
-            const serverSidePropsMiddleware = await (0, middlewares_1.getServerSidePropsAsMiddleware)(page.file, vite);
-            const renderMiddleware = (0, render_1.createRenderMiddleware)(page, {
-                enablePlatformDetection,
-                renderFunction,
-                viteConfig
-            });
-            const pageMiddlewares = options.isProduction ? [
-                ...prevMiddlewares,
-                serverSidePropsMiddleware,
-                renderMiddleware
-            ] : [
-                HMRMiddleware,
-                renderMiddleware
-            ];
-            router.get(page.expressRoute, ...pageMiddlewares);
-            // Error middleware separado  
-            router.use(page.expressRoute, (0, middlewares_1.createPageErrorHandler)(page.file, vite));
-        }
-    };
-    // Setup routes asynchronously but don't block router creation
-    setupRoutes().catch(console.error);
-    return router;
-}
-function listDetectedPages() {
-    return (0, pages_1.getPages)();
-}
-var pages_2 = require("./pages");
-Object.defineProperty(exports, "getPages", { enumerable: true, get: function () { return pages_2.getPages; } });
+var pages_1 = require("./pages");
+Object.defineProperty(exports, "getPages", { enumerable: true, get: function () { return pages_1.getPages; } });

package/dist/routes/dispatcher.d.ts

@@ -0,0 +1,37 @@
+import type { RequestHandler } from 'express';
+import type { RouteEntry, RouteManifest } from './types';
+declare global {
+    namespace Express {
+        interface Request {
+            /** La ruta que atendió esta petición. La usa el manejador de errores. */
+            ressRoute?: RouteEntry;
+            /**
+             * Los parámetros de la URL.
+             *
+             * Express reasigna `req.params` al entrar a cada router anidado, así que
+             * los valores que el despachador extrajo se perderían en el camino. Acá
+             * quedan en un campo propio, y `req.params` se mantiene por compatibilidad
+             * con quien ya lo lee.
+             */
+            ressParams?: Record<string, string | string[]>;
+        }
+    }
+}
+/** Cómo se arma la cadena de middlewares de una entrada. */
+export type ChainBuilder = (entry: RouteEntry) => Promise<RequestHandler[]>;
+/**
+ * Un único punto de entrada para todas las rutas.
+ *
+ * El modelo anterior registraba una ruta de Express por página, lo que obligaba
+ * a traducir cada patrón a la sintaxis de Express —que no puede expresar un
+ * catch-all opcional ni un grupo— y dejaba la precedencia en manos del orden de
+ * registro. Acá el manifest decide, y Express sólo ve un middleware.
+ *
+ * Las cadenas se construyen una vez, no por petición. `chains` se reemplaza
+ * entero cuando el manifest cambia en desarrollo, de modo que una petición nunca
+ * ve una mezcla de dos versiones.
+ */
+export declare function createDispatcher(getState: () => {
+    manifest: RouteManifest;
+    chains: Map<string, RequestHandler[]>;
+}): RequestHandler;

package/dist/routes/dispatcher.js

@@ -0,0 +1,69 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createDispatcher = createDispatcher;
+/**
+ * Un único punto de entrada para todas las rutas.
+ *
+ * El modelo anterior registraba una ruta de Express por página, lo que obligaba
+ * a traducir cada patrón a la sintaxis de Express —que no puede expresar un
+ * catch-all opcional ni un grupo— y dejaba la precedencia en manos del orden de
+ * registro. Acá el manifest decide, y Express sólo ve un middleware.
+ *
+ * Las cadenas se construyen una vez, no por petición. `chains` se reemplaza
+ * entero cuando el manifest cambia en desarrollo, de modo que una petición nunca
+ * ve una mezcla de dos versiones.
+ */
+function createDispatcher(getState) {
+    return async (req, res, next) => {
+        const { manifest, chains } = getState();
+        const match = manifest.match(req.path ?? req.url ?? '/');
+        // Sin match no es un 404 todavía: puede haber middlewares detrás que sepan
+        // atenderla, y decidirlo acá les quitaría la oportunidad.
+        if (!match)
+            return next();
+        const chain = chains.get(match.entry.pageId);
+        if (!chain)
+            return next();
+        req.ressParams = match.params;
+        req.params = match.params;
+        req.ressRoute = match.entry;
+        runChain(chain, req, res, next);
+    };
+}
+/**
+ * Ejecuta la cadena respetando el contrato de Express.
+ *
+ * Cada middleware decide si sigue: `next()` avanza, `next(error)` corta y
+ * propaga. Un throw síncrono se convierte en `next(error)` para que no quede una
+ * petición colgada.
+ */
+function runChain(chain, req, res, done) {
+    let index = 0;
+    const step = (error) => {
+        if (error)
+            return done(error);
+        const handler = chain[index++];
+        if (!handler)
+            return done();
+        // Un middleware asíncrono puede llamar a `next()` y rechazar después. Sin
+        // esta guarda, el rechazo volvería a entrar a la cadena sobre una respuesta
+        // que ya se envió, y el fallo sería un ERR_HTTP_HEADERS_SENT en vez de la
+        // página de error.
+        let advanced = false;
+        const once = (err) => {
+            if (advanced)
+                return;
+            advanced = true;
+            step(err);
+        };
+        try {
+            const result = handler(req, res, once);
+            if (result instanceof Promise)
+                result.catch(once);
+        }
+        catch (err) {
+            once(err);
+        }
+    };
+    step();
+}

package/dist/routes/manifest.d.ts

@@ -0,0 +1,17 @@
+import { type RouteManifest, type RouteManifestData } from './types';
+/**
+ * El manifest ya indexado.
+ *
+ * Las rutas estáticas —la mayoría de un proyecto— se resuelven con una consulta
+ * a un mapa. Sólo las que tienen parámetros recorren la lista, y ya viene
+ * ordenada por precedencia, así que la primera que matchea es la que gana.
+ */
+export declare function createRouteManifest(data: RouteManifestData): RouteManifest;
+export declare function serializeRouteManifest(data: RouteManifestData): string;
+/**
+ * Lee un manifest emitido por el build.
+ *
+ * La versión se comprueba a propósito: un manifest de un formato anterior
+ * produciría fallos de ruteo difíciles de atribuir, y el mensaje dice qué hacer.
+ */
+export declare function loadRouteManifest(raw: string): RouteManifest;

package/dist/routes/manifest.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createRouteManifest = createRouteManifest;
+exports.serializeRouteManifest = serializeRouteManifest;
+exports.loadRouteManifest = loadRouteManifest;
+const match_1 = require("./match");
+const types_1 = require("./types");
+/**
+ * El manifest ya indexado.
+ *
+ * Las rutas estáticas —la mayoría de un proyecto— se resuelven con una consulta
+ * a un mapa. Sólo las que tienen parámetros recorren la lista, y ya viene
+ * ordenada por precedencia, así que la primera que matchea es la que gana.
+ */
+function createRouteManifest(data) {
+    const entries = data.entries;
+    const byPageId = new Map(entries.map((e) => [e.pageId, e]));
+    const staticIndex = new Map();
+    for (const entry of entries) {
+        if (entry.segments.every((s) => s.kind === 'static')) {
+            staticIndex.set(`${entry.kind} ${entry.pattern}`, entry);
+        }
+    }
+    return {
+        entries,
+        match(pathname, options = {}) {
+            const kinds = options.kinds ?? ['page'];
+            const clean = '/' + pathname.split('?')[0].split('#')[0].split('/').filter(Boolean).join('/');
+            for (const kind of kinds) {
+                const exact = staticIndex.get(`${kind} ${clean}`);
+                if (exact)
+                    return { entry: exact, params: {} };
+            }
+            return (0, match_1.matchEntries)(entries, pathname, options);
+        },
+        get: (pageId) => byPageId.get(pageId),
+        byKind: (kind) => entries.filter((e) => e.kind === kind),
+    };
+}
+function serializeRouteManifest(data) {
+    return JSON.stringify(data, null, 2);
+}
+/**
+ * Lee un manifest emitido por el build.
+ *
+ * La versión se comprueba a propósito: un manifest de un formato anterior
+ * produciría fallos de ruteo difíciles de atribuir, y el mensaje dice qué hacer.
+ */
+function loadRouteManifest(raw) {
+    const data = JSON.parse(raw);
+    if (data.version !== types_1.ROUTE_MANIFEST_VERSION) {
+        throw new Error(`[ress] El manifest de rutas es de la versión ${data.version} y este ress.js espera la ` +
+            `${types_1.ROUTE_MANIFEST_VERSION}. Volvé a construir el proyecto.`);
+    }
+    return createRouteManifest(data);
+}

package/dist/routes/match.d.ts

@@ -0,0 +1,20 @@
+import type { MatchOptions, RouteEntry, RouteMatch, RouteSegment } from './types';
+/**
+ * Parte una URL en segmentos.
+ *
+ * Se descartan la consulta y el fragmento, y la barra final no distingue: `/about`
+ * y `/about/` son la misma ruta.
+ */
+export declare function splitPath(pathname: string): string[];
+/**
+ * ¿Esta ruta atiende esta URL?
+ *
+ * Sin expresiones regulares: se recorre segmento a segmento. Una regex construida
+ * a partir de un patrón es difícil de auditar y fácil de romper con un carácter
+ * que había que escapar — y el modelo anterior tenía justamente ese defecto:
+ * `/page1` matcheaba `/page1/cualquier/cosa` porque su regex no exigía consumir
+ * la URL entera.
+ */
+export declare function matchSegments(segments: readonly RouteSegment[], parts: readonly string[]): Record<string, string | string[]> | undefined;
+/** La primera entrada que atiende esta URL, recorriendo en orden de precedencia. */
+export declare function matchEntries(entries: readonly RouteEntry[], pathname: string, options?: MatchOptions): RouteMatch | undefined;

package/dist/routes/match.js

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.splitPath = splitPath;
+exports.matchSegments = matchSegments;
+exports.matchEntries = matchEntries;
+/**
+ * Parte una URL en segmentos.
+ *
+ * Se descartan la consulta y el fragmento, y la barra final no distingue: `/about`
+ * y `/about/` son la misma ruta.
+ */
+function splitPath(pathname) {
+    const clean = pathname.split('?')[0].split('#')[0];
+    return clean.split('/').filter(Boolean);
+}
+/**
+ * ¿Esta ruta atiende esta URL?
+ *
+ * Sin expresiones regulares: se recorre segmento a segmento. Una regex construida
+ * a partir de un patrón es difícil de auditar y fácil de romper con un carácter
+ * que había que escapar — y el modelo anterior tenía justamente ese defecto:
+ * `/page1` matcheaba `/page1/cualquier/cosa` porque su regex no exigía consumir
+ * la URL entera.
+ */
+function matchSegments(segments, parts) {
+    const params = {};
+    let index = 0;
+    for (const segment of segments) {
+        if (segment.kind === 'catchAll' || segment.kind === 'optionalCatchAll') {
+            const rest = parts.slice(index).map(decode);
+            // Un catch-all obligatorio necesita al menos un segmento; el opcional
+            // acepta ninguno y entrega una lista vacía.
+            if (segment.kind === 'catchAll' && rest.length === 0)
+                return undefined;
+            params[segment.value] = rest;
+            return params;
+        }
+        const part = parts[index];
+        if (part === undefined)
+            return undefined;
+        if (segment.kind === 'static') {
+            if (part !== segment.value)
+                return undefined;
+        }
+        else {
+            params[segment.value] = decode(part);
+        }
+        index++;
+    }
+    // La URL tiene que quedar consumida entera: lo que sobra no lo atiende esta ruta.
+    return index === parts.length ? params : undefined;
+}
+function decode(value) {
+    try {
+        return decodeURIComponent(value);
+    }
+    catch {
+        // Una secuencia de escape inválida no es motivo para fallar la petición: el
+        // valor crudo es lo que el cliente pidió.
+        return value;
+    }
+}
+/** La primera entrada que atiende esta URL, recorriendo en orden de precedencia. */
+function matchEntries(entries, pathname, options = {}) {
+    const kinds = options.kinds ?? ['page'];
+    const parts = splitPath(pathname);
+    for (const entry of entries) {
+        if (!kinds.includes(entry.kind))
+            continue;
+        const params = matchSegments(entry.segments, parts);
+        if (params)
+            return { entry, params };
+    }
+    return undefined;
+}

package/dist/routes/parse.d.ts

@@ -0,0 +1,31 @@
+import type { RouteEntryKind, RouteSegment } from './types';
+/**
+ * Convierte la ubicación de un archivo en un patrón de ruta.
+ *
+ * Notación:
+ *
+ * | En el archivo | En la URL |
+ * |---|---|
+ * | `users/perfil.tsx` | `/users/perfil` |
+ * | `users/index.tsx` | `/users` |
+ * | `users/[id].tsx` | `/users/:id` |
+ * | `docs/[...slug].tsx` | `/docs/` y todo lo que siga |
+ * | `shop/[[...filtros]].tsx` | `/shop` y todo lo que siga |
+ * | `(marketing)/about.tsx` | `/about` — el grupo no aporta segmento |
+ */
+export interface ParsedRoute {
+    pattern: string;
+    segments: RouteSegment[];
+    paramNames: string[];
+    groups: string[];
+}
+export declare function parseRoutePattern(sourceFile: string, pagesDir?: string): ParsedRoute;
+/**
+ * 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.
+ */
+export declare function pageIdFromFile(sourceFile: string, pagesDir?: string): string;
+/** Qué clase de entrada es, según dónde vive el archivo. */
+export declare function classifyEntry(sourceFile: string, pagesDir?: string): RouteEntryKind;