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

package/dist/runtime/module-loader.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Carga de módulos de usuario — páginas y middlewares.
+ *
+ * La interfaz es única para desarrollo y producción, de modo que quien carga un
+ * módulo no tenga que saber en qué entorno corre.
+ */
+/** Superficie mínima de un entorno de desarrollo de Vite que necesitamos. */
+export interface FetchableEnvironment {
+    fetchModule(id: string, importer?: string, options?: {
+        cached?: boolean;
+        startOffset?: number;
+    }): Promise<Record<string, unknown>>;
+}
+export interface ModuleLoader {
+    /** Carga un módulo de usuario y devuelve sus exports. */
+    load<T = Record<string, unknown>>(id: string): Promise<T>;
+    /**
+     * Descarta de la caché el módulo correspondiente a un archivo, para que la
+     * próxima carga lo vuelva a evaluar. Sin argumento, descarta todo.
+     */
+    invalidate(file?: string): void;
+    /** Libera recursos. Idempotente. */
+    close(): Promise<void>;
+}
+/**
+ * Cargador de desarrollo.
+ *
+ * El runner se construye sobre `environment.fetchModule()` y no sobre el getter
+ * `RunnableDevEnvironment.runner`, porque ese getter arma su transporte de forma
+ * síncrona leyendo `environment.hot.api.outsideEmitter`, propiedad que sólo
+ * existe una vez que el servidor empezó a escuchar. Ress.js carga módulos de
+ * usuario durante el registro de rutas, antes de ese momento, y ahí el getter
+ * falla con `Cannot read properties of undefined (reading 'outsideEmitter')`.
+ * `fetchModule()` es un método asíncrono plano, disponible en todos los tipos de
+ * entorno y en cualquier punto del ciclo de vida.
+ *
+ * El runner se crea una vez por servidor, nunca por petición: `runner.import()`
+ * mantiene su propia caché de módulos y crear uno por petición la anularía.
+ *
+ * Esa caché es también la razón de `invalidate()`. El runner corre con `hmr:
+ * false` —el canal de HMR no es utilizable durante el registro de rutas—, así
+ * que nada descarta un módulo cuando su archivo cambia. Sin invalidación
+ * explícita, editar una página o un middleware no tendría efecto hasta reiniciar
+ * el servidor. `createDevRuntime` conecta el watcher de Vite a este método.
+ */
+export declare function createDevModuleLoader(env: FetchableEnvironment): Promise<ModuleLoader>;
+/**
+ * Cargador de producción: importa el artefacto ya compilado.
+ *
+ * `resolveId` traduce el identificador lógico de una página al path de su
+ * artefacto de servidor. Se recibe como parámetro para que la traducción sea
+ * responsabilidad de quien conoce la correspondencia — F-018 la toma del
+ * manifest de rutas, donde el build la registró.
+ */
+export declare function createProdModuleLoader(resolveId: (id: string) => string): ModuleLoader;

package/dist/runtime/module-loader.js

@@ -0,0 +1,122 @@
+"use strict";
+/**
+ * Carga de módulos de usuario — páginas y middlewares.
+ *
+ * La interfaz es única para desarrollo y producción, de modo que quien carga un
+ * módulo no tenga que saber en qué entorno corre.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createDevModuleLoader = createDevModuleLoader;
+exports.createProdModuleLoader = createProdModuleLoader;
+/**
+ * Cargador de desarrollo.
+ *
+ * El runner se construye sobre `environment.fetchModule()` y no sobre el getter
+ * `RunnableDevEnvironment.runner`, porque ese getter arma su transporte de forma
+ * síncrona leyendo `environment.hot.api.outsideEmitter`, propiedad que sólo
+ * existe una vez que el servidor empezó a escuchar. Ress.js carga módulos de
+ * usuario durante el registro de rutas, antes de ese momento, y ahí el getter
+ * falla con `Cannot read properties of undefined (reading 'outsideEmitter')`.
+ * `fetchModule()` es un método asíncrono plano, disponible en todos los tipos de
+ * entorno y en cualquier punto del ciclo de vida.
+ *
+ * El runner se crea una vez por servidor, nunca por petición: `runner.import()`
+ * mantiene su propia caché de módulos y crear uno por petición la anularía.
+ *
+ * Esa caché es también la razón de `invalidate()`. El runner corre con `hmr:
+ * false` —el canal de HMR no es utilizable durante el registro de rutas—, así
+ * que nada descarta un módulo cuando su archivo cambia. Sin invalidación
+ * explícita, editar una página o un middleware no tendría efecto hasta reiniciar
+ * el servidor. `createDevRuntime` conecta el watcher de Vite a este método.
+ */
+async function createDevModuleLoader(env) {
+    const { ModuleRunner, ESModulesEvaluator, createNodeImportMeta } = await import(
+    /* @vite-ignore */ 'vite/module-runner');
+    const runner = new ModuleRunner({
+        transport: {
+            // `normalizeModuleRunnerTransport` ya desempaqueta el payload, así que
+            // `payload.data` llega como `{ id, name, data: args }`.
+            invoke: async (payload) => {
+                const { name, data: args } = payload.data;
+                if (name === 'fetchModule') {
+                    const [id, importer, options] = args;
+                    return { result: await env.fetchModule(id, importer, options) };
+                }
+                if (name === 'getBuiltins') {
+                    // Los módulos corren en el proceso Node anfitrión, que ya tiene
+                    // acceso nativo a los built-ins.
+                    return { result: [] };
+                }
+                return {
+                    error: {
+                        name: 'Error',
+                        message: `[ress] invocación inesperada del module runner: ${name}`,
+                    },
+                };
+            },
+        },
+        createImportMeta: createNodeImportMeta,
+        sourcemapInterceptor: false,
+        hmr: false,
+    }, new ESModulesEvaluator());
+    let closed = false;
+    return {
+        load: (id) => runner.import(id),
+        invalidate: (file) => {
+            if (!file) {
+                runner.clearCache();
+                return;
+            }
+            // Un archivo puede tener varios módulos evaluados si se importó con
+            // distintas queries. Se descartan todos.
+            const mods = runner.evaluatedModules.getModulesByFile(file);
+            if (!mods || mods.size === 0) {
+                // El archivo no está en el grafo de este runner: nada que descartar.
+                return;
+            }
+            for (const mod of mods) {
+                runner.evaluatedModules.invalidateModule(mod);
+            }
+        },
+        close: async () => {
+            if (closed)
+                return;
+            closed = true;
+            await runner.close();
+        },
+    };
+}
+/**
+ * Cargador de producción: importa el artefacto ya compilado.
+ *
+ * `resolveId` traduce el identificador lógico de una página al path de su
+ * artefacto de servidor. Se recibe como parámetro para que la traducción sea
+ * responsabilidad de quien conoce la correspondencia — F-018 la toma del
+ * manifest de rutas, donde el build la registró.
+ */
+function createProdModuleLoader(resolveId) {
+    return {
+        load: async (id) => {
+            const target = resolveId(id);
+            // El loader ESM de Node interpreta una ruta `C:\\...` como una URL con
+            // esquema `c:` en Windows. Convertir sólo las rutas de archivos mantiene
+            // intactos los identificadores `node:`, `data:` y `file:` usados por
+            // integraciones y tests.
+            const specifier = process.platform === 'win32' && !isModuleSpecifier(target)
+                ? (0, node_url_1.pathToFileURL)(node_path_1.default.resolve(target)).href
+                : target;
+            return (await import(/* @vite-ignore */ specifier));
+        },
+        // En producción los artefactos no cambian mientras el servidor corre.
+        invalidate: () => { },
+        close: async () => { },
+    };
+}
+function isModuleSpecifier(value) {
+    return /^(?:node:|data:|file:|https?:)/i.test(value);
+}
+const node_path_1 = __importDefault(require("node:path"));
+const node_url_1 = require("node:url");

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

@@ -0,0 +1,55 @@
+/**
+ * Runtime de producción.
+ *
+ * No instancia Vite: en producción se sirven artefactos ya construidos.
+ */
+import { type ResolvedSecurityOptions } from '../security';
+import type { RouteManifest } from '../routes/types';
+import { type DevRuntimeOptions, type RessRuntime } from './dev-server';
+/**
+ * Dónde quedó el artefacto de servidor de una página.
+ *
+ * La traducción del nombre la hace `toCompiledPath`, que es la única
+ * implementación del framework: antes vivía repetida en tres lugares con reglas
+ * que ya habían divergido —una sólo recortaba `.ts`, otra sólo `\w+` dentro de
+ * los corchetes—.
+ */
+export declare function resolveServerModulePath(pageFile: string, ssrOutDir?: string): string;
+/**
+ * Traduce la identidad lógica que pide el runtime al chunk registrado.
+ *
+ * Los middlewares se buscan en la lista que registró el build. La resolución
+ * por convención queda sólo para un manifest armado sin ella (un runtime
+ * propio). Una página conocida jamás cae por ese camino: si su `buildChunk`
+ * falta, `resolveServerModule` falla y exige rebuild.
+ */
+export declare function resolveProductionModuleId(id: string, manifest: RouteManifest, options?: {
+    root?: string;
+    ssrOutDir?: string;
+}): string;
+export declare function createProdRuntime(opts?: {
+    clientOutDir?: string;
+    ssrOutDir?: string;
+    /** Prefijo de las URL de artefactos: prefijo de ruta o CDN. */
+    assetPrefix?: string;
+}): Promise<RessRuntime>;
+/**
+ * Assets estáticos en producción.
+ *
+ * Cada archivo se cachea según lo que su nombre garantice: los que llevan el
+ * hash de su contenido pueden guardarse para siempre, el resto tiene que
+ * revalidarse. El default es revalidar, porque un archivo guardado como
+ * inmutable por error no se puede invalidar en el navegador de quien ya lo bajó.
+ */
+export declare function createProdAssetMiddleware(clientOutDir?: string, options?: {
+    security?: ResolvedSecurityOptions;
+    /** Archivos que emitió el build, tomados del manifest. */
+    buildOutputs?: ReadonlySet<string>;
+}): Promise<import("express-serve-static-core").Router>;
+/** Los archivos que el build de cliente emitió, según el manifest. */
+export declare function buildOutputsFrom(manifest: Record<string, {
+    file: string;
+    css?: string[];
+}>): Set<string>;
+/** Punto de entrada único: elige el runtime según el entorno. */
+export declare function createRuntime(isProduction: boolean, base?: string, assetPrefix?: string, devOptions?: DevRuntimeOptions): Promise<RessRuntime>;

package/dist/runtime/prod-server.js

@@ -0,0 +1,188 @@
+"use strict";
+/**
+ * Runtime de producción.
+ *
+ * No instancia Vite: en producción se sirven artefactos ya construidos.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveServerModulePath = resolveServerModulePath;
+exports.resolveProductionModuleId = resolveProductionModuleId;
+exports.createProdRuntime = createProdRuntime;
+exports.createProdAssetMiddleware = createProdAssetMiddleware;
+exports.buildOutputsFrom = buildOutputsFrom;
+exports.createRuntime = createRuntime;
+const node_crypto_1 = require("node:crypto");
+const promises_1 = __importDefault(require("node:fs/promises"));
+const node_path_1 = __importDefault(require("node:path"));
+const express_1 = __importDefault(require("express"));
+const security_1 = require("../security");
+const module_loader_1 = require("./module-loader");
+const assets_1 = require("../variants/assets");
+const manifest_1 = require("../routes/manifest");
+const module_1 = require("../routes/module");
+const environments_1 = require("../plugin/environments");
+const module_extensions_1 = require("../fs/module-extensions");
+const dev_server_1 = require("./dev-server");
+const template_1 = require("./template");
+/**
+ * El manifest de rutas que emitió el build.
+ *
+ * Si no está —un proyecto construido con una versión anterior— se escanea, para
+ * no dejar el servidor sin arrancar por un archivo que se puede regenerar.
+ */
+async function loadRoutes(clientOutDir) {
+    const manifestPath = node_path_1.default.join(node_path_1.default.dirname(clientOutDir), 'route-manifest.json');
+    let raw;
+    try {
+        raw = await promises_1.default.readFile(manifestPath, 'utf-8');
+    }
+    catch {
+        throw new Error(`[ress] No se encontró el manifest de rutas en ${manifestPath}. ` +
+            'Ejecutá el build antes de arrancar en producción.');
+    }
+    // Un manifest ilegible o de otra versión se reporta tal cual. Escanear el
+    // proyecto como respaldo era peor que fallar: en un servidor que sólo tiene
+    // `dist/` el escaneo no encuentra nada, y en vez de un error claro el servidor
+    // arranca y responde 404 en todas las rutas.
+    return (0, manifest_1.loadRouteManifest)(raw);
+}
+/**
+ * Dónde quedó el artefacto de servidor de una página.
+ *
+ * La traducción del nombre la hace `toCompiledPath`, que es la única
+ * implementación del framework: antes vivía repetida en tres lugares con reglas
+ * que ya habían divergido —una sólo recortaba `.ts`, otra sólo `\w+` dentro de
+ * los corchetes—.
+ */
+function resolveServerModulePath(pageFile, ssrOutDir = environments_1.OUT_DIR.ssr) {
+    return node_path_1.default.resolve(process.cwd(), ssrOutDir, (0, module_extensions_1.toCompiledPath)(pageFile));
+}
+/**
+ * Traduce la identidad lógica que pide el runtime al chunk registrado.
+ *
+ * Los middlewares se buscan en la lista que registró el build. La resolución
+ * por convención queda sólo para un manifest armado sin ella (un runtime
+ * propio). Una página conocida jamás cae por ese camino: si su `buildChunk`
+ * falta, `resolveServerModule` falla y exige rebuild.
+ */
+function resolveProductionModuleId(id, manifest, options = {}) {
+    const root = options.root ?? process.cwd();
+    const ssrOutDir = options.ssrOutDir ?? environments_1.OUT_DIR.ssr;
+    const entry = manifest.entries.find((candidate) => candidate.server.devId === id ||
+        `/${candidate.sourceFile.replace(/\\/g, '/')}` === id.replace(/\\/g, '/'));
+    if (entry) {
+        return (0, module_1.resolveServerModule)(entry, {
+            root,
+            serverOutDir: ssrOutDir,
+            isProduction: true,
+        });
+    }
+    const middleware = manifest.middlewares?.find((candidate) => candidate.server.devId.replace(/^\//, '') === id.replace(/\\/g, '/').replace(/^\//, ''));
+    if (middleware) {
+        return (0, module_1.resolveServerModule)({ pageId: middleware.file, server: middleware.server }, { root, serverOutDir: ssrOutDir, isProduction: true });
+    }
+    if (/\.middlewares\.[^.]+$|(?:^|\/)middlewares\.[^.]+$/.test(id)) {
+        return node_path_1.default.resolve(root, ssrOutDir, (0, module_extensions_1.toCompiledPath)(id));
+    }
+    throw new Error(`[ress] El módulo "${id}" no figura en el manifest de rutas del build.`);
+}
+async function createProdRuntime(opts = {}) {
+    const clientOutDir = opts.clientOutDir ?? environments_1.OUT_DIR.client;
+    const ssrOutDir = opts.ssrOutDir ?? environments_1.OUT_DIR.ssr;
+    const manifestPath = node_path_1.default.join(clientOutDir, '.vite', 'manifest.json');
+    let manifest = {};
+    try {
+        manifest = JSON.parse(await promises_1.default.readFile(manifestPath, 'utf-8'));
+    }
+    catch {
+        throw new Error(`[ress] No se encontró el manifest del cliente en ${manifestPath}. ` +
+            'Ejecutá el build antes de arrancar en producción.');
+    }
+    const templateHtml = await (0, template_1.readTemplateHtml)();
+    // El manifest lo emite el build y es obligatorio en producción: arrancar sin
+    // él respondería 404 para todo en un despliegue que no incluye fuentes.
+    const routes = await loadRoutes(clientOutDir);
+    const catalog = (0, assets_1.createProdVariantCatalog)(routes, manifest);
+    const moduleLoader = (0, module_loader_1.createProdModuleLoader)((id) => resolveProductionModuleId(id, routes, { root: process.cwd(), ssrOutDir }));
+    return {
+        vite: null,
+        moduleLoader,
+        templateHtml,
+        isProduction: true,
+        catalog,
+        routes,
+        assets: (0, assets_1.createProdAssetIndex)(catalog, manifest, opts.assetPrefix ?? '/'),
+        buildOutputs: buildOutputsFrom(manifest),
+        buildId: await readBuildId(clientOutDir, manifest),
+        // Los artefactos no cambian mientras el servidor corre.
+        onSourceChange: () => () => { },
+        close: async () => {
+            await moduleLoader.close();
+        },
+    };
+}
+/**
+ * Assets estáticos en producción.
+ *
+ * Cada archivo se cachea según lo que su nombre garantice: los que llevan el
+ * hash de su contenido pueden guardarse para siempre, el resto tiene que
+ * revalidarse. El default es revalidar, porque un archivo guardado como
+ * inmutable por error no se puede invalidar en el navegador de quien ya lo bajó.
+ */
+async function createProdAssetMiddleware(clientOutDir = environments_1.OUT_DIR.client, options = {}) {
+    const compression = (await import('compression')).default;
+    const sirv = (await import('sirv')).default;
+    const security = options.security ?? (0, security_1.resolveSecurityOptions)();
+    const buildOutputs = options.buildOutputs ?? new Set();
+    const middlewares = express_1.default.Router();
+    middlewares.use(compression());
+    middlewares.use(sirv(clientOutDir, {
+        extensions: [],
+        etag: true,
+        setHeaders(res, pathname) {
+            if (security.headers.contentTypeOptions) {
+                res.setHeader('X-Content-Type-Options', 'nosniff');
+            }
+            res.setHeader('Cache-Control', (0, security_1.assetCacheControl)((0, security_1.classifyAsset)(pathname, buildOutputs), security));
+        },
+    }));
+    return middlewares;
+}
+/**
+ * El identificador del build vigente.
+ *
+ * Lo escribe el plugin junto al manifest de rutas. Un build anterior a ese
+ * archivo se identifica por el hash de su manifest de cliente, que cambia con
+ * cualquier artefacto nuevo.
+ */
+async function readBuildId(clientOutDir, manifest) {
+    try {
+        const id = (await promises_1.default.readFile(node_path_1.default.join(node_path_1.default.dirname(clientOutDir), environments_1.BUILD_ID_FILE), 'utf-8')).trim();
+        if (id)
+            return id;
+    }
+    catch {
+        // Se identifica por el manifest.
+    }
+    return (0, node_crypto_1.createHash)('sha256').update(JSON.stringify(manifest)).digest('hex').slice(0, 32);
+}
+/** Los archivos que el build de cliente emitió, según el manifest. */
+function buildOutputsFrom(manifest) {
+    const out = new Set();
+    for (const chunk of Object.values(manifest)) {
+        if (chunk.file)
+            out.add(chunk.file);
+        for (const css of chunk.css ?? [])
+            out.add(css);
+    }
+    return out;
+}
+/** Punto de entrada único: elige el runtime según el entorno. */
+async function createRuntime(isProduction, base = '/', assetPrefix = base, devOptions = {}) {
+    if (isProduction)
+        return createProdRuntime({ assetPrefix });
+    return (0, dev_server_1.createDevRuntime)(base, assetPrefix, devOptions);
+}

package/dist/runtime/template.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Documento mínimo para proyectos que no necesitan personalizar el shell HTML.
+ * Los marcadores son consumidos por generateCompleteHTML.
+ */
+export declare const DEFAULT_TEMPLATE_HTML = "<!doctype html>\n<html lang=\"en\">\n  <head><!--app-head--></head>\n  <body><div id=\"root\"><!--app-html--></div></body>\n</html>\n";
+/**
+ * Lee el shell del proyecto cuando existe y cae a la plantilla del paquete si no.
+ * Sólo ENOENT es una ausencia esperable; otros errores deben ser visibles.
+ */
+export declare function readTemplateHtml(root?: string): Promise<string>;

package/dist/runtime/template.js

@@ -0,0 +1,33 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_TEMPLATE_HTML = void 0;
+exports.readTemplateHtml = readTemplateHtml;
+const promises_1 = __importDefault(require("node:fs/promises"));
+const node_path_1 = __importDefault(require("node:path"));
+/**
+ * Documento mínimo para proyectos que no necesitan personalizar el shell HTML.
+ * Los marcadores son consumidos por generateCompleteHTML.
+ */
+exports.DEFAULT_TEMPLATE_HTML = `<!doctype html>
+<html lang="en">
+  <head><!--app-head--></head>
+  <body><div id="root"><!--app-html--></div></body>
+</html>
+`;
+/**
+ * Lee el shell del proyecto cuando existe y cae a la plantilla del paquete si no.
+ * Sólo ENOENT es una ausencia esperable; otros errores deben ser visibles.
+ */
+async function readTemplateHtml(root = process.cwd()) {
+    try {
+        return await promises_1.default.readFile(node_path_1.default.join(root, 'index.html'), 'utf-8');
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+        return exports.DEFAULT_TEMPLATE_HTML;
+    }
+}

package/dist/security/client-props.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Qué parte del estado del servidor viaja al cliente.
+ *
+ * La regla es enumerar lo que **sí** viaja. La inversa —enumerar lo que se
+ * excluye— falla sola: cada middleware que agregue una clave nueva a
+ * `res.locals` la expone hasta que alguien se acuerde de agregarla a la lista de
+ * exclusión, y nadie se acuerda.
+ */
+import type { ClientPropsPolicy } from './config';
+/**
+ * Las props que se serializan en el documento.
+ *
+ * Las props del **servidor** no cambian: el componente sigue recibiendo todo
+ * durante el renderizado. La restricción es sólo sobre lo que se escribe en el
+ * HTML.
+ */
+export declare function pickClientProps(locals: Record<string, unknown>, policy: ClientPropsPolicy): Record<string, unknown>;
+/**
+ * Qué quedó afuera.
+ *
+ * Se usa para avisar en desarrollo: una página que renderiza en el servidor con
+ * datos que el cliente no tiene hidrata distinto, y ese desajuste es difícil de
+ * diagnosticar sin que alguien lo nombre.
+ */
+export declare function withheldKeys(locals: Record<string, unknown>, exposed: Record<string, unknown>): string[];

package/dist/security/client-props.js

@@ -0,0 +1,51 @@
+"use strict";
+/**
+ * Qué parte del estado del servidor viaja al cliente.
+ *
+ * La regla es enumerar lo que **sí** viaja. La inversa —enumerar lo que se
+ * excluye— falla sola: cada middleware que agregue una clave nueva a
+ * `res.locals` la expone hasta que alguien se acuerde de agregarla a la lista de
+ * exclusión, y nadie se acuerda.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pickClientProps = pickClientProps;
+exports.withheldKeys = withheldKeys;
+/**
+ * Las props que se serializan en el documento.
+ *
+ * Las props del **servidor** no cambian: el componente sigue recibiendo todo
+ * durante el renderizado. La restricción es sólo sobre lo que se escribe en el
+ * HTML.
+ */
+function pickClientProps(locals, policy) {
+    // Sin prototipo: así una clave `__proto__` en los datos es una clave más y no
+    // altera el objeto.
+    const out = Object.create(null);
+    // `serverSideProps` es lo que la página pidió explícitamente para el cliente:
+    // es el contrato que ya usan las aplicaciones, y por eso sigue activo.
+    if (policy.exposeServerSideProps && isPlainObject(locals?.serverSideProps)) {
+        Object.assign(out, locals.serverSideProps);
+    }
+    // La válvula para el estado público que aporta un middleware, como el idioma.
+    for (const key of policy.expose) {
+        if (Object.hasOwn(locals ?? {}, key))
+            out[key] = locals[key];
+    }
+    // Configuración del servidor: nunca fue para el cliente, bajo ninguna política.
+    delete out.htmlConfig;
+    delete out.pageConfig;
+    return { ...out };
+}
+/**
+ * Qué quedó afuera.
+ *
+ * Se usa para avisar en desarrollo: una página que renderiza en el servidor con
+ * datos que el cliente no tiene hidrata distinto, y ese desajuste es difícil de
+ * diagnosticar sin que alguien lo nombre.
+ */
+function withheldKeys(locals, exposed) {
+    return Object.keys(locals ?? {}).filter((key) => key !== 'htmlConfig' && key !== 'pageConfig' && key !== 'serverSideProps' && !(key in exposed));
+}
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/dist/security/config.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Opciones de seguridad del framework.
+ *
+ * Se resuelven **una vez al arrancar**, no por petición: el objeto resultante
+ * está completo y congelado, y viaja por el contexto de seguridad hasta quien lo
+ * necesite. Resolver defaults por petición sería trabajo repetido y, peor,
+ * abriría la puerta a que dos partes de la misma respuesta usen valores
+ * distintos.
+ */
+/** Qué claves del estado del servidor viajan al cliente. */
+export interface ClientPropsPolicy {
+    /** Claves de `res.locals` que se serializan. Nada más viaja. */
+    expose: string[];
+    /** Si `res.locals.serverSideProps` se expone completo. */
+    exposeServerSideProps: boolean;
+}
+export interface HstsOptions {
+    maxAge: number;
+    includeSubDomains?: boolean;
+    preload?: boolean;
+}
+export interface SecurityOptions {
+    clientProps?: Partial<ClientPropsPolicy>;
+    maxStateBytes?: number;
+    onStateOverLimit?: 'warn' | 'error';
+    /**
+     * @deprecated Ya no existe: la detección de plataforma usa siempre el
+     * User-Agent. Declararla lo rechaza `resolveSecurityOptions` al arrancar.
+     */
+    varyOnUserAgent?: never;
+    /**
+     * Si la plataforma detectada se escribe en el documento.
+     *
+     * `'auto'` la escribe sólo cuando la página tiene variantes. Una página que no
+     * varía devuelve el mismo documento a cualquier cliente, y escribir en él quién
+     * lo pidió lo vuelve distinto para cada uno sin que nada lo declare: una caché
+     * intermedia le serviría a un teléfono la plataforma de un televisor. Cuando no
+     * viaja, el cliente la detecta por su cuenta con las mismas reglas.
+     */
+    serializePlatform?: 'auto' | 'always' | 'never';
+    headers?: {
+        contentTypeOptions?: boolean;
+        referrerPolicy?: string | false;
+        frameOptions?: 'DENY' | 'SAMEORIGIN' | false;
+        hsts?: HstsOptions | false;
+    };
+    cache?: {
+        html?: string;
+        immutableMaxAge?: number;
+        staticMaxAge?: number;
+    };
+    csp?: {
+        enabled?: boolean;
+        reportOnly?: boolean;
+        directives?: Record<string, string[] | false>;
+        reportUri?: string;
+    };
+    head?: {
+        allowScriptTags?: boolean;
+        extraTagAllowlist?: string[];
+    };
+    dev?: {
+        allowedHosts?: string[];
+        allowedOrigins?: string[] | false;
+    };
+}
+export interface ResolvedSecurityOptions {
+    clientProps: ClientPropsPolicy;
+    maxStateBytes: number;
+    onStateOverLimit: 'warn' | 'error';
+    serializePlatform: 'auto' | 'always' | 'never';
+    headers: {
+        contentTypeOptions: boolean;
+        referrerPolicy: string | false;
+        frameOptions: 'DENY' | 'SAMEORIGIN' | false;
+        hsts: HstsOptions | false;
+    };
+    cache: {
+        html: string;
+        immutableMaxAge: number;
+        staticMaxAge: number;
+    };
+    csp: {
+        enabled: boolean;
+        reportOnly: boolean;
+        directives: Record<string, string[] | false>;
+        reportUri?: string;
+    };
+    head: {
+        allowScriptTags: boolean;
+        extraTagAllowlist: string[];
+    };
+    dev: {
+        allowedHosts?: string[];
+        allowedOrigins: string[] | false;
+    };
+}
+/**
+ * Defaults.
+ *
+ * Dos ausencias son deliberadas y están explicadas donde se aplican:
+ * `frameOptions` apagada, porque ress.js sirve páginas embebidas por diseño, y
+ * `hsts` apagada, porque activarla sobre un dominio que todavía sirve HTTP por
+ * alguna ruta lo deja inaccesible.
+ */
+export declare function resolveSecurityOptions(user?: SecurityOptions): ResolvedSecurityOptions;
+/** Lo que necesita saber cada parte de la respuesta sobre esta petición. */
+export interface SecurityContext {
+    /** Autoriza los bloques inline ante la política de contenido. */
+    nonce?: string;
+    isProduction: boolean;
+    options: ResolvedSecurityOptions;
+    /** Ruta de la petición, para que los avisos digan dónde. */
+    route: string;
+    /**
+     * Ejes por los que varía esta página. Vacío significa que su documento es el
+     * mismo para cualquier cliente, y entonces nada que dependa del cliente puede
+     * escribirse en él.
+     */
+    varyBy?: readonly string[];
+}