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

package/dist/isr/preview.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PREVIEW_COOKIE = exports.PREVIEW_HEADER = void 0;
+exports.isPreviewRequest = isPreviewRequest;
+const node_crypto_1 = require("node:crypto");
+exports.PREVIEW_HEADER = 'x-ress-preview';
+exports.PREVIEW_COOKIE = '__ress_preview';
+const digest = (value) => (0, node_crypto_1.createHash)('sha256').update(value).digest();
+/** Compara en tiempo constante: el largo del valor tampoco se filtra, porque se comparan hashes. */
+function matches(candidate, secret) {
+    if (!candidate)
+        return false;
+    return (0, node_crypto_1.timingSafeEqual)(digest(candidate), digest(secret));
+}
+function cookieValue(header, name) {
+    if (!header)
+        return undefined;
+    for (const part of header.split(';')) {
+        const index = part.indexOf('=');
+        if (index === -1 || part.slice(0, index).trim() !== name)
+            continue;
+        try {
+            return decodeURIComponent(part.slice(index + 1).trim());
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return undefined;
+}
+/** ¿La petición trae el secreto de vista previa? Sin secreto configurado, nunca. */
+function isPreviewRequest(req, secret) {
+    if (!secret)
+        return false;
+    const header = req.headers[exports.PREVIEW_HEADER];
+    return (matches(Array.isArray(header) ? header[0] : header, secret) ||
+        matches(cookieValue(req.headers.cookie, exports.PREVIEW_COOKIE), secret));
+}

package/dist/isr/public-request.d.ts

@@ -0,0 +1,50 @@
+import type { Request } from 'express';
+import type { RequestPlatform } from './key';
+/**
+ * Las cabeceras que describen a la plataforma, no a la persona.
+ *
+ * Son las únicas del cliente que una página incremental puede ver: la entrada
+ * se separa por plataforma, así que lo que dependa de ellas queda en la entrada
+ * correcta. Cualquier otra cabecera podría personalizar un documento que después
+ * se sirve a todos.
+ */
+export declare function platformHeaderNames(includeUserAgent?: boolean): Set<string>;
+/**
+ * El origen de la petición según Express.
+ *
+ * `req.protocol` y `req.host` respetan `trust proxy`: sin él, un
+ * `X-Forwarded-Host` del visitante no cuenta. Es la única vista del origen que
+ * llega a la página, y forma parte de la clave: dos hosts nunca comparten
+ * entrada, y una cabecera falsificada sólo crea una entrada que nadie más pide.
+ */
+export declare function requestOrigin(live: Request): {
+    protocol: string;
+    host: string;
+};
+export interface PublicRequestInput {
+    /** Ruta más la búsqueda canónica. */
+    url: string;
+    query: Record<string, string | string[]>;
+    platform: RequestPlatform;
+    /** El de `requestOrigin`: también está en la clave. */
+    origin: {
+        protocol: string;
+        host: string;
+    };
+    /** Si la detección no usa el User-Agent, la página tampoco lo ve. */
+    includeUserAgent?: boolean;
+}
+/** Qué leyó la generación de la petición pública. */
+export declare function publicRequestUsage(req: Request): {
+    readsPlatform: boolean;
+};
+/**
+ * La petición con la que se genera una página incremental.
+ *
+ * Es un objeto propio y no una vista de la petición real: heredar de ella
+ * dejaría a la generación escribiendo sobre un socket que ya terminó y
+ * registrando listeners en otra petición. Lleva sólo lo público —ruta,
+ * parámetros declarados y plataforma—, nunca cookies ni credenciales: por
+ * construcción, lo que produzca es igual para cualquier visitante.
+ */
+export declare function createPublicRequest(live: Request, input: PublicRequestInput): Request;

package/dist/isr/public-request.js

@@ -0,0 +1,108 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.platformHeaderNames = platformHeaderNames;
+exports.requestOrigin = requestOrigin;
+exports.publicRequestUsage = publicRequestUsage;
+exports.createPublicRequest = createPublicRequest;
+const node_events_1 = require("node:events");
+const platform_1 = require("@ressjs/platform");
+const platform_tokens_1 = require("../variants/platform-tokens");
+/**
+ * Las cabeceras que describen a la plataforma, no a la persona.
+ *
+ * Son las únicas del cliente que una página incremental puede ver: la entrada
+ * se separa por plataforma, así que lo que dependa de ellas queda en la entrada
+ * correcta. Cualquier otra cabecera podría personalizar un documento que después
+ * se sirve a todos.
+ */
+function platformHeaderNames(includeUserAgent = true) {
+    return new Set([
+        ...platform_1.PLATFORM_VARY_HEADERS.filter((name) => includeUserAgent || name.toLowerCase() !== 'user-agent'),
+        platform_1.HEADER_OVERRIDE,
+        ...platform_tokens_1.defaultPlatformRegistry.edge.map((rule) => rule.header),
+    ].map((name) => name.toLowerCase()));
+}
+/**
+ * El origen de la petición según Express.
+ *
+ * `req.protocol` y `req.host` respetan `trust proxy`: sin él, un
+ * `X-Forwarded-Host` del visitante no cuenta. Es la única vista del origen que
+ * llega a la página, y forma parte de la clave: dos hosts nunca comparten
+ * entrada, y una cabecera falsificada sólo crea una entrada que nadie más pide.
+ */
+function requestOrigin(live) {
+    const host = live.host ?? String(live.headers?.host ?? 'localhost');
+    return { protocol: live.protocol ?? 'http', host: host.toLowerCase() };
+}
+/** Qué leyó la generación de la petición pública. */
+function publicRequestUsage(req) {
+    return req.ressUsage ?? { readsPlatform: false };
+}
+/**
+ * La petición con la que se genera una página incremental.
+ *
+ * Es un objeto propio y no una vista de la petición real: heredar de ella
+ * dejaría a la generación escribiendo sobre un socket que ya terminó y
+ * registrando listeners en otra petición. Lleva sólo lo público —ruta,
+ * parámetros declarados y plataforma—, nunca cookies ni credenciales: por
+ * construcción, lo que produzca es igual para cualquier visitante.
+ */
+function createPublicRequest(live, input) {
+    const allowed = platformHeaderNames(input.includeUserAgent ?? true);
+    const headers = {};
+    for (const [name, value] of Object.entries(live.headers)) {
+        if (value !== undefined && allowed.has(name.toLowerCase()))
+            headers[name.toLowerCase()] = value;
+    }
+    // El origen viene de la vista de Express, no de cabeceras crudas: la página
+    // no ve `X-Forwarded-*` ni `Accept`, que no forman parte de la clave.
+    const { protocol, host } = input.origin;
+    headers.host = host;
+    const path = input.url.split('?')[0] || '/';
+    // Si la página lee una cabecera de plataforma, su HTML puede cambiar según
+    // el cliente. ress.js lo separa por plataforma en su caché, pero una CDN no
+    // lo sabría: esa página no se le declara compartible. Se registra la lectura
+    // en vez de pedirle a la página que lo declare.
+    const usage = { readsPlatform: false };
+    const tracked = new Proxy(headers, {
+        get(target, name) {
+            if (typeof name === 'string' && allowed.has(name.toLowerCase()))
+                usage.readsPlatform = true;
+            return Reflect.get(target, name);
+        },
+        ownKeys(target) {
+            // Recorrerlas todas (un spread, `Object.entries`) también es leerlas.
+            if (Object.keys(target).some((name) => allowed.has(name)))
+                usage.readsPlatform = true;
+            return Reflect.ownKeys(target);
+        },
+    });
+    const header = (name) => tracked[name.toLowerCase()];
+    const req = Object.assign(new node_events_1.EventEmitter(), {
+        method: 'GET',
+        url: input.url,
+        originalUrl: input.url,
+        baseUrl: '',
+        path,
+        query: { ...input.query },
+        params: { ...(live.ressParams ?? live.params) },
+        ressParams: live.ressParams ? { ...live.ressParams } : undefined,
+        ressRoute: live.ressRoute,
+        ressPlatform: input.platform,
+        headers: tracked,
+        ressUsage: usage,
+        rawHeaders: [],
+        httpVersion: '1.1',
+        protocol,
+        secure: protocol === 'https',
+        hostname: host.replace(/:\d+$/, ''),
+        host,
+        cookies: {},
+        signedCookies: {},
+        socket: { encrypted: protocol === 'https' },
+        connection: { encrypted: protocol === 'https' },
+        get: header,
+        header,
+    });
+    return req;
+}

package/dist/isr/response.d.ts

@@ -0,0 +1,41 @@
+import type { Response } from 'express';
+import type { CapturedResponse, HeaderValue, ResolvedPageRendering } from './types';
+export type ServedState = 'MISS' | 'HIT' | 'STALE' | 'BYPASS';
+/**
+ * ¿Se puede guardar lo que produjo la generación?
+ *
+ * `full` es la respuesta completa (para tipo y política de caché, que pueden
+ * venir de la semilla); `delta` es lo que agregó la página.
+ */
+export declare function cacheability(full: CapturedResponse, delta: Record<string, HeaderValue>): {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+/** Guarda una plantilla: el nonce de la política nunca se reutiliza entre respuestas. */
+export declare function normalizeForCache(response: CapturedResponse): CapturedResponse & {
+    noncePlaceholder?: string;
+};
+/** Una copia servible de la entrada, con un nonce nuevo si la política lo usa. */
+export declare function materialize(entry: CapturedResponse & {
+    noncePlaceholder?: string;
+}): CapturedResponse;
+/**
+ * Lo que una página incremental le dice a una CDN.
+ *
+ * Con nonce no se declara compartible: una CDN serviría el mismo nonce a todos,
+ * que es exactamente lo que el nonce existe para impedir. Sin plazo tampoco:
+ * la entrada vence con el reinicio del proceso y una CDN no se enteraría.
+ */
+export declare function isrCacheControl(rendering: ResolvedPageRendering, usesNonce: boolean): string | undefined;
+/**
+ * Envía lo capturado por la respuesta real.
+ *
+ * Los middlewares ya pusieron lo suyo en esta petición; lo capturado va encima,
+ * como en el camino normal. `res.send` calcula longitud y ETag, y la compresión
+ * actúa sobre esta respuesta según lo que acepte este cliente.
+ */
+/** Lo mismo que el resto del framework: cualquier directiva que deje guardarla a una CDN. */
+export declare function isSharedCacheControl(value: HeaderValue | undefined): boolean;
+export declare function applyCaptured(res: Response, response: CapturedResponse, state: ServedState): void;

package/dist/isr/response.js

@@ -0,0 +1,128 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.cacheability = cacheability;
+exports.normalizeForCache = normalizeForCache;
+exports.materialize = materialize;
+exports.isrCacheControl = isrCacheControl;
+exports.isSharedCacheControl = isSharedCacheControl;
+exports.applyCaptured = applyCaptured;
+const security_1 = require("../security");
+const capture_1 = require("./capture");
+const public_request_1 = require("./public-request");
+const NONCE_PLACEHOLDER = '__RESS_ISR_NONCE__';
+const ONE_YEAR = 31_536_000;
+/**
+ * `Vary` que una entrada puede declarar sin quedar mal identificada: la clave ya
+ * separa por plataforma, y la codificación se negocia en cada petición.
+ */
+let safeVary;
+function isSafeVary(field) {
+    safeVary ??= new Set([...(0, public_request_1.platformHeaderNames)(), 'accept-encoding']);
+    return safeVary.has(field.toLowerCase());
+}
+/**
+ * ¿Se puede guardar lo que produjo la generación?
+ *
+ * `full` es la respuesta completa (para tipo y política de caché, que pueden
+ * venir de la semilla); `delta` es lo que agregó la página.
+ */
+function cacheability(full, delta) {
+    if (full.status !== 200)
+        return { ok: false, reason: `respondió ${full.status}` };
+    if (!String(full.headers['content-type'] ?? '').toLowerCase().includes('text/html')) {
+        return { ok: false, reason: 'no respondió HTML' };
+    }
+    if (delta['set-cookie'] !== undefined)
+        return { ok: false, reason: 'entregó una cookie' };
+    if (/\bno-store\b/i.test(String(full.headers['cache-control'] ?? ''))) {
+        return { ok: false, reason: 'declaró Cache-Control: no-store' };
+    }
+    const foreign = (0, capture_1.varyFields)(delta.vary).filter((field) => !isSafeVary(field));
+    if (foreign.length) {
+        return { ok: false, reason: `varía por ${foreign.join(', ')}, que no forma parte de la clave` };
+    }
+    return { ok: true };
+}
+const mapHeaders = (headers, fn) => Object.fromEntries(Object.entries(headers).map(([name, value]) => [name, Array.isArray(value) ? value.map(fn) : fn(value)]));
+/** Guarda una plantilla: el nonce de la política nunca se reutiliza entre respuestas. */
+function normalizeForCache(response) {
+    const csp = response.headers['content-security-policy'] ?? response.headers['content-security-policy-report-only'];
+    const nonce = (Array.isArray(csp) ? csp.join(';') : csp)?.match(/'nonce-([^']+)'/)?.[1];
+    if (!nonce)
+        return response;
+    const replace = (value) => value.replaceAll(nonce, NONCE_PLACEHOLDER);
+    return {
+        ...response,
+        body: replace(response.body),
+        headers: mapHeaders(response.headers, replace),
+        noncePlaceholder: NONCE_PLACEHOLDER,
+    };
+}
+/** Una copia servible de la entrada, con un nonce nuevo si la política lo usa. */
+function materialize(entry) {
+    const placeholder = entry.noncePlaceholder;
+    if (!placeholder)
+        return entry;
+    const nonce = (0, security_1.createNonce)();
+    const replace = (value) => value.replaceAll(placeholder, nonce);
+    return { status: entry.status, body: replace(entry.body), headers: mapHeaders(entry.headers, replace) };
+}
+/**
+ * Lo que una página incremental le dice a una CDN.
+ *
+ * Con nonce no se declara compartible: una CDN serviría el mismo nonce a todos,
+ * que es exactamente lo que el nonce existe para impedir. Sin plazo tampoco:
+ * la entrada vence con el reinicio del proceso y una CDN no se enteraría.
+ */
+function isrCacheControl(rendering, usesNonce) {
+    if (usesNonce || rendering.revalidate === false)
+        return undefined;
+    const swr = rendering.expire !== undefined ? rendering.expire - rendering.revalidate : ONE_YEAR;
+    return `public, max-age=0, s-maxage=${rendering.revalidate}, stale-while-revalidate=${swr}`;
+}
+/**
+ * Envía lo capturado por la respuesta real.
+ *
+ * Los middlewares ya pusieron lo suyo en esta petición; lo capturado va encima,
+ * como en el camino normal. `res.send` calcula longitud y ETag, y la compresión
+ * actúa sobre esta respuesta según lo que acepte este cliente.
+ */
+/** Lo mismo que el resto del framework: cualquier directiva que deje guardarla a una CDN. */
+function isSharedCacheControl(value) {
+    return (0, security_1.isShareableCacheControl)(Array.isArray(value) ? value.join(',') : value);
+}
+/**
+ * Una respuesta que entrega una cookie nunca se declara compartible.
+ *
+ * La generación no ve las cookies que ponen los middlewares —se sacan de la
+ * semilla para detectar las de la página—, así que la comprobación va sobre la
+ * respuesta real y lo más tarde posible: al escribir las cabeceras, cuando ya
+ * pasó cualquiera que agregue la suya en ese momento (una sesión, por ejemplo).
+ */
+function forbidSharedCacheWithCookies(res) {
+    const writeHead = res.writeHead.bind(res);
+    res.writeHead = ((...args) => {
+        if (res.getHeader('Set-Cookie') !== undefined && isSharedCacheControl(res.getHeader('Cache-Control'))) {
+            res.setHeader('Cache-Control', 'private, no-cache');
+        }
+        return writeHead(...args);
+    });
+}
+function applyCaptured(res, response, state) {
+    forbidSharedCacheWithCookies(res);
+    for (const [name, value] of Object.entries(response.headers)) {
+        if (name === 'vary') {
+            for (const field of (0, capture_1.varyFields)(value))
+                res.vary(field);
+        }
+        else if (name === 'set-cookie') {
+            res.append('Set-Cookie', value);
+        }
+        else {
+            res.setHeader(name, value);
+        }
+    }
+    res.status(response.status);
+    res.setHeader('X-Ress-Cache', state);
+    res.send(response.body);
+}

package/dist/isr/store.d.ts

@@ -0,0 +1,42 @@
+import type { CacheLookup, IsrEntry } from './types';
+export interface MemoryIsrStoreOptions {
+    maxEntries: number;
+    maxBytes: number;
+    /** Tiempo máximo de una generación compartida. */
+    timeoutMs: number;
+}
+export declare class GenerationTimeoutError extends Error {
+    constructor(key: string, timeoutMs: number);
+}
+/**
+ * La caché incremental de un proceso.
+ *
+ * LRU por cantidad y por bytes: con rutas dinámicas el conjunto de URLs es
+ * abierto, y un tope sólo por cantidad deja crecer la memoria con páginas grandes.
+ * Cada router crea la suya, así que dos aplicaciones en el mismo proceso no
+ * comparten documentos.
+ */
+export declare class MemoryIsrStore {
+    #private;
+    readonly options: MemoryIsrStoreOptions;
+    constructor(options: MemoryIsrStoreOptions);
+    lookup(key: string, now?: number): CacheLookup;
+    set(entry: IsrEntry): void;
+    delete(key: string): void;
+    /**
+     * Una sola generación por clave a la vez.
+     *
+     * Quien llega mientras hay una en curso recibe la misma promesa: una avalancha
+     * sobre una entrada nueva o vencida renderiza una vez. Si vence el tiempo, la
+     * clave se libera para que la próxima petición pueda intentarlo; lo que la
+     * generación abandonada produzca después no lo consume nadie, así que nunca
+     * llega a guardarse.
+     */
+    run<T>(key: string, work: () => Promise<T>): Promise<T>;
+    inFlight(key: string): boolean;
+    clear(): void;
+    get size(): number;
+    get bytes(): number;
+}
+/** La clave sin el build ni la plataforma completa, para los mensajes. */
+export declare function readableKey(key: string): string;

package/dist/isr/store.js

@@ -0,0 +1,108 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MemoryIsrStore = exports.GenerationTimeoutError = void 0;
+exports.readableKey = readableKey;
+class GenerationTimeoutError extends Error {
+    constructor(key, timeoutMs) {
+        super(`[ress] La generación ISR excedió ${timeoutMs} ms y se abandonó (${readableKey(key)}).`);
+        this.name = 'GenerationTimeoutError';
+    }
+}
+exports.GenerationTimeoutError = GenerationTimeoutError;
+/**
+ * La caché incremental de un proceso.
+ *
+ * LRU por cantidad y por bytes: con rutas dinámicas el conjunto de URLs es
+ * abierto, y un tope sólo por cantidad deja crecer la memoria con páginas grandes.
+ * Cada router crea la suya, así que dos aplicaciones en el mismo proceso no
+ * comparten documentos.
+ */
+class MemoryIsrStore {
+    options;
+    #entries = new Map();
+    #inFlight = new Map();
+    #bytes = 0;
+    constructor(options) {
+        this.options = options;
+    }
+    lookup(key, now = Date.now()) {
+        const entry = this.#entries.get(key);
+        if (!entry)
+            return { state: 'missing' };
+        // Leer también es usar: se mueve al final del orden de desalojo.
+        this.#entries.delete(key);
+        this.#entries.set(key, entry);
+        if (entry.revalidateMs === null)
+            return { state: 'fresh', entry };
+        const age = now - entry.generatedAt;
+        if (age < entry.revalidateMs)
+            return { state: 'fresh', entry };
+        if (entry.expireMs !== null && age >= entry.expireMs)
+            return { state: 'expired', entry };
+        return { state: 'stale', entry };
+    }
+    set(entry) {
+        this.delete(entry.key);
+        // Una entrada que no entra sola desalojaría toda la caché para no caber igual.
+        if (entry.bytes > this.options.maxBytes)
+            return;
+        this.#entries.set(entry.key, entry);
+        this.#bytes += entry.bytes;
+        for (const oldest of this.#entries.keys()) {
+            if (this.#entries.size <= this.options.maxEntries && this.#bytes <= this.options.maxBytes)
+                break;
+            this.delete(oldest);
+        }
+    }
+    delete(key) {
+        const previous = this.#entries.get(key);
+        if (!previous)
+            return;
+        this.#entries.delete(key);
+        this.#bytes -= previous.bytes;
+    }
+    /**
+     * Una sola generación por clave a la vez.
+     *
+     * Quien llega mientras hay una en curso recibe la misma promesa: una avalancha
+     * sobre una entrada nueva o vencida renderiza una vez. Si vence el tiempo, la
+     * clave se libera para que la próxima petición pueda intentarlo; lo que la
+     * generación abandonada produzca después no lo consume nadie, así que nunca
+     * llega a guardarse.
+     */
+    run(key, work) {
+        const running = this.#inFlight.get(key);
+        if (running)
+            return running;
+        let timer;
+        const timeout = new Promise((_, reject) => {
+            timer = setTimeout(() => reject(new GenerationTimeoutError(key, this.options.timeoutMs)), this.options.timeoutMs);
+            timer.unref?.();
+        });
+        const task = Promise.race([Promise.resolve().then(work), timeout]).finally(() => {
+            clearTimeout(timer);
+            if (this.#inFlight.get(key) === task)
+                this.#inFlight.delete(key);
+        });
+        this.#inFlight.set(key, task);
+        return task;
+    }
+    inFlight(key) {
+        return this.#inFlight.has(key);
+    }
+    clear() {
+        this.#entries.clear();
+        this.#bytes = 0;
+    }
+    get size() {
+        return this.#entries.size;
+    }
+    get bytes() {
+        return this.#bytes;
+    }
+}
+exports.MemoryIsrStore = MemoryIsrStore;
+/** La clave sin el build ni la plataforma completa, para los mensajes. */
+function readableKey(key) {
+    return key.split('\0').at(-1) ?? key;
+}

package/dist/isr/types.d.ts

@@ -0,0 +1,62 @@
+export type RenderingMode = 'ssr' | 'isr';
+/**
+ * Cómo se renderiza una página. Vive en el export estático `pageConfig`: el
+ * router tiene que decidir si responde desde la caché antes de ejecutar nada de
+ * la petición, así que no puede depender de lo que devuelva `getServerSideProps`.
+ */
+export interface PageRenderingConfig {
+    /** `ssr` (por defecto) renderiza cada petición; `isr` sirve desde la caché. */
+    renderingMode?: RenderingMode;
+    /**
+     * Segundos durante los que una entrada es fresca (entero mayor que cero), o
+     * `false`: no vence por tiempo, sólo con un build nuevo. Por defecto `false`.
+     */
+    revalidate?: number | false;
+    /**
+     * Techo de antigüedad en segundos. Pasado, la entrada ya no se sirve vencida:
+     * se regenera antes de responder. Requiere un `revalidate` numérico menor.
+     */
+    expire?: number;
+    /** `false` entrega HTML y CSS sin script de entrada ni estado. Por defecto `true`. */
+    hydrate?: boolean;
+    /** Parámetros de consulta que forman parte de la identidad de la página. */
+    searchParams?: string[];
+}
+/** La configuración de render ya validada, en las unidades que usa el runtime. */
+export interface ResolvedPageRendering {
+    mode: RenderingMode;
+    hydrate: boolean;
+    /** `null`: no vence por tiempo. */
+    revalidateMs: number | null;
+    /** `null`: sin techo. */
+    expireMs: number | null;
+    /** Únicos y ordenados. */
+    searchParams: string[];
+    /** En segundos, para `Cache-Control`. */
+    revalidate: number | false;
+    expire?: number;
+}
+export type HeaderValue = string | string[];
+/** Lo que produjo una generación: sólo lo que agregó la página, no el transporte. */
+export interface CapturedResponse {
+    status: number;
+    /** En minúsculas. */
+    headers: Record<string, HeaderValue>;
+    body: string;
+}
+export interface IsrEntry extends CapturedResponse {
+    key: string;
+    generatedAt: number;
+    revalidateMs: number | null;
+    expireMs: number | null;
+    /** Marcador que reemplazó al nonce original, si la respuesta tenía uno. */
+    noncePlaceholder?: string;
+    bytes: number;
+}
+export type CacheState = 'fresh' | 'stale' | 'expired' | 'missing';
+export type CacheLookup = {
+    state: 'missing';
+} | {
+    state: Exclude<CacheState, 'missing'>;
+    entry: IsrEntry;
+};

package/dist/isr/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/pages.d.ts

@@ -1,9 +1,11 @@
-import type { PlatformInfo } from './platform';
+import { type ExtensionPolicy } from './fs/module-extensions';
 export interface PageInfo {
     route: string;
     expressRoute: string;
     file: string;
     abs: string;
+    /** Identificador estable, compartido con el catálogo de variantes. */
+    pageId: string;
 }
 /**
  * Convierte rutas estilo Next.js con parámetros dinámicos a formato Express
@@ -13,18 +15,17 @@ export interface PageInfo {
  * '/home' → '/home' (sin cambios)
  */
 export declare function convertRouteToExpress(route: string): string;
-export declare function getPages(): PageInfo[];
-export declare function getViteInput(): Record<string, string>;
+export declare function getPages(policy?: ExtensionPolicy): PageInfo[];
+/**
+ * Entradas del entorno de servidor: las páginas más sus middlewares.
+ *
+ * El entorno de cliente no aparece acá: sus entradas salen del catálogo de
+ * variantes, porque una página produce una por cada plataforma que atiende.
+ */
 export declare function getViteSSRInput(): Record<string, string>;
-export declare function loadManifest(distPath?: string): Promise<any>;
 /**
  * Convierte una ruta de página TypeScript a su equivalente compilado en producción
  *
  * @param pageFile - Ruta del archivo de página (relativa: "app/pages/pokedex/index.tsx" o absoluta: "/path/to/app/pages/pokedex/index.tsx")
  * @returns Ruta absoluta del archivo compilado (ej: "/path/to/project/dist/server/pokedex/index.js")
  */
-export declare function getCompiledProdPage(pageFile: string): string;
-export declare function resolvePlatformCSS(basePath: string, platform: PlatformInfo): Promise<string>;
-export declare function generateTempEntries(distPath?: string, platformInfo?: PlatformInfo): Promise<string[]>;
-export declare function generateSingleEntry(page: PageInfo, entryPath: string, preferredScssFile: string): Promise<void>;
-export declare function getClientEntriesInput(distPath?: string): Promise<Record<string, string>>;