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

package/dist/security/serialize.js

@@ -0,0 +1,146 @@
+"use strict";
+/**
+ * Serialización del estado que viaja al cliente.
+ *
+ * El JSON se embebe en un `<script>` inline, así que además de ser JSON válido
+ * tiene que sobrevivir a dos gramáticas más: la del HTML, que busca `</script`,
+ * `<!--` y `<!` dentro del elemento, y la de JavaScript, donde U+2028 y U+2029
+ * son terminadores de línea que parten un literal de cadena.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SerializationError = void 0;
+exports.serializeState = serializeState;
+exports.renderStateScript = renderStateScript;
+exports.checkStateSize = checkStateSize;
+const escape_1 = require("./escape");
+/**
+ * Los cinco caracteres a escapar, y ninguno más.
+ *
+ * Escapar `<` neutraliza `</script>`, `<!--`, `<script` y `<!` de una sola vez,
+ * sin tener que reconocer secuencias. `&` va en la lista para que un analizador
+ * que decodifique entidades no pueda reconstruir un `<`.
+ *
+ * Los cinco reemplazos son escapes JSON válidos: `<` **es** `<` para
+ * `JSON.parse`, así que el valor no cambia, sólo su representación.
+ */
+const ESCAPE_MAP = {
+    '<': '\\u003C',
+    '>': '\\u003E',
+    '&': '\\u0026',
+    '\u2028': '\\u2028',
+    '\u2029': '\\u2029',
+};
+const ESCAPE_RE = /[<>&\u2028\u2029]/g;
+class SerializationError extends Error {
+    reason;
+    path;
+    constructor(reason, path) {
+        super(`[ress] no se pudo serializar el estado en ${path}: ${reason}`);
+        this.reason = reason;
+        this.path = path;
+        this.name = 'SerializationError';
+    }
+}
+exports.SerializationError = SerializationError;
+/**
+ * Serializa un valor para embeberlo en un `<script>` inline.
+ *
+ * El resultado es JSON válido y `JSON.parse` lo devuelve idéntico al original.
+ */
+function serializeState(value, path = '$') {
+    let json;
+    try {
+        json = JSON.stringify(value, createGuard(path));
+    }
+    catch (err) {
+        throw new SerializationError(describe(err), path);
+    }
+    if (json === undefined)
+        return 'undefined';
+    return json.replace(ESCAPE_RE, (c) => ESCAPE_MAP[c]);
+}
+/**
+ * Detecta lo que no es serializable **antes** de que falle, para poder decir
+ * dónde.
+ *
+ * `JSON.stringify` sobre una estructura cíclica dice "Converting circular
+ * structure to JSON" y no nombra la propiedad; sobre una función no dice nada,
+ * simplemente la omite. Las dos cosas son difíciles de diagnosticar en una
+ * página que dejó de hidratar.
+ *
+ * `Date` es la excepción deliberada: se convierte a su forma ISO y así llega al
+ * cliente. Es el comportamiento de siempre.
+ */
+function createGuard(root) {
+    const seen = new WeakSet();
+    const paths = new WeakMap();
+    return function guard(key, value) {
+        const parent = this;
+        const path = key === ''
+            ? root
+            : `${(parent && paths.get(parent)) ?? root}${/^\d+$/.test(key) ? `[${key}]` : `.${key}`}`;
+        const type = typeof value;
+        if (type === 'function')
+            throw new SerializationError('es una función', path);
+        if (type === 'bigint')
+            throw new SerializationError('es un BigInt', path);
+        if (type === 'symbol')
+            throw new SerializationError('es un Symbol', path);
+        if (value instanceof Map)
+            throw new SerializationError('es un Map', path);
+        if (value instanceof Set)
+            throw new SerializationError('es un Set', path);
+        if (value && type === 'object' && !(value instanceof Date)) {
+            if (seen.has(value)) {
+                throw new SerializationError('la estructura tiene un ciclo', path);
+            }
+            seen.add(value);
+            paths.set(value, path);
+        }
+        return value;
+    };
+}
+function describe(err) {
+    if (err instanceof SerializationError)
+        throw err;
+    return err instanceof Error ? err.message : String(err);
+}
+/**
+ * El bloque `<script>` con el estado.
+ *
+ * Recibe el nonce cuando hay política de contenido: sin él, el bloque no se
+ * ejecuta y la hidratación no encuentra sus props.
+ */
+function renderStateScript(blocks, nonce) {
+    const attrs = nonce ? ` nonce="${(0, escape_1.escapeAttrValue)(nonce)}"` : '';
+    const body = blocks
+        .map((b) => `window.${b.varName}=${serializeState(b.value, '$.' + b.varName)};`)
+        .join('');
+    return `<script${attrs}>${body}</script>`;
+}
+/**
+ * Cuánto pesa el estado que viaja.
+ *
+ * Se mide sobre el string **ya serializado y escapado**, que es lo que
+ * efectivamente se transfiere, y en bytes y no en caracteres, porque un
+ * carácter fuera de ASCII ocupa más de uno.
+ */
+function checkStateSize(serialized, limitBytes, value) {
+    const bytes = Buffer.byteLength(serialized, 'utf8');
+    const overLimit = bytes > limitBytes;
+    const heaviest = overLimit && value && typeof value === 'object'
+        ? Object.entries(value)
+            .map(([key, v]) => ({ key, bytes: safeSize(v) }))
+            .sort((a, b) => b.bytes - a.bytes)
+            .slice(0, 3)
+        : [];
+    return { bytes, overLimit, heaviest };
+}
+function safeSize(value) {
+    try {
+        return Buffer.byteLength(JSON.stringify(value) ?? '', 'utf8');
+    }
+    catch {
+        return 0;
+    }
+}

package/dist/variants/assets.d.ts

@@ -0,0 +1,33 @@
+import type { AssetIndex, VariantCatalog } from './types';
+import type { RouteManifest } from '../routes/types';
+/**
+ * Artefactos en desarrollo.
+ *
+ * Vite sirve el módulo virtual directamente, así que el guion es su propia URL.
+ * Los estilos no se listan porque el módulo los importa y Vite los inyecta.
+ */
+export declare function createDevAssetIndex(catalog: VariantCatalog, base?: string): AssetIndex;
+/** Forma del manifest que emite el entorno de cliente. */
+interface ManifestChunk {
+    file: string;
+    css?: string[];
+    name?: string;
+    src?: string;
+}
+/**
+ * Reconstruye el catálogo de producción desde artefactos del build.
+ *
+ * Volver a escanear `app/pages` al arrancar haría que un despliegue compuesto
+ * sólo por `dist/` perdiera todas sus variantes. El manifest del cliente ya
+ * enumera exactamente las entradas que se construyeron, incluida la variante.
+ */
+export declare function createProdVariantCatalog(routes: RouteManifest, manifest: Record<string, ManifestChunk>): VariantCatalog;
+/**
+ * Artefactos en producción, tomados del manifest del cliente.
+ *
+ * El manifest se lee una vez al arrancar y se pasa a un índice por página y
+ * variante, de modo que servir una petición sea una consulta en memoria y no una
+ * búsqueda.
+ */
+export declare function createProdAssetIndex(catalog: VariantCatalog, manifest: Record<string, ManifestChunk>, base?: string): AssetIndex;
+export {};

package/dist/variants/assets.js

@@ -0,0 +1,144 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createDevAssetIndex = createDevAssetIndex;
+exports.createProdVariantCatalog = createProdVariantCatalog;
+exports.createProdAssetIndex = createProdAssetIndex;
+const catalog_1 = require("./catalog");
+const platform_tokens_1 = require("./platform-tokens");
+const platform_1 = require("@ressjs/platform");
+const dev_styles_1 = require("../runtime/dev-styles");
+/**
+ * Artefactos en desarrollo.
+ *
+ * Vite sirve el módulo virtual directamente, así que el guion es su propia URL.
+ * Los estilos no se listan porque el módulo los importa y Vite los inyecta.
+ */
+function createDevAssetIndex(catalog, base = '/') {
+    return {
+        find(pageId, variantSuffix) {
+            const variant = catalog.variantsByPage.get(pageId)?.find((v) => v.suffix === variantSuffix);
+            if (!variant)
+                return undefined;
+            // El prefijo lo agrega el framework, no Vite: el pipeline de petición lo
+            // quita antes de que Vite vea la URL, así que su propio `base` es `/`.
+            const prefix = joinBase(base, '').replace(/\/$/, '');
+            return {
+                js: joinBase(base, '@id/' + (0, catalog_1.virtualModuleIdFor)(pageId, variantSuffix)),
+                css: [],
+                ...(variant.styleFile ? { devStyles: [(0, dev_styles_1.directStyleUrl)(prefix, (0, dev_styles_1.projectFileUrl)(variant.styleFile))] } : {}),
+            };
+        },
+    };
+}
+/**
+ * Reconstruye el catálogo de producción desde artefactos del build.
+ *
+ * Volver a escanear `app/pages` al arrancar haría que un despliegue compuesto
+ * sólo por `dist/` perdiera todas sus variantes. El manifest del cliente ya
+ * enumera exactamente las entradas que se construyeron, incluida la variante.
+ */
+function createProdVariantCatalog(routes, manifest) {
+    const buildEntries = [];
+    const variantsByPage = new Map();
+    const pagesById = new Map();
+    const seen = new Set();
+    for (const entry of routes.entries) {
+        if (entry.kind === 'api')
+            continue;
+        pagesById.set(entry.pageId, { route: entry.pattern, pageFile: entry.sourceFile });
+    }
+    for (const [key, chunk] of Object.entries(manifest)) {
+        const parsed = parseVirtualEntry(key) ?? (chunk.src ? parseVirtualEntry(chunk.src) : undefined);
+        if (!parsed || seen.has(`${parsed.pageId} ${parsed.suffix}`))
+            continue;
+        const page = pagesById.get(parsed.pageId);
+        if (!page)
+            continue;
+        seen.add(`${parsed.pageId} ${parsed.suffix}`);
+        const variant = {
+            suffix: parsed.suffix,
+            tags: (0, platform_1.parseVariantSuffix)(parsed.suffix, platform_tokens_1.defaultPlatformRegistry, key),
+        };
+        const variants = variantsByPage.get(parsed.pageId) ?? [];
+        variants.push(variant);
+        variantsByPage.set(parsed.pageId, variants);
+        buildEntries.push({
+            pageId: parsed.pageId,
+            route: page.route,
+            pageFile: page.pageFile,
+            variant,
+            virtualId: (0, catalog_1.virtualModuleIdFor)(parsed.pageId, parsed.suffix),
+        });
+    }
+    buildEntries.sort((a, b) => a.pageId === b.pageId
+        ? a.variant.suffix.localeCompare(b.variant.suffix)
+        : a.pageId.localeCompare(b.pageId));
+    for (const variants of variantsByPage.values()) {
+        variants.sort((a, b) => a.suffix.localeCompare(b.suffix));
+    }
+    return { buildEntries, variantsByPage, pagesById };
+}
+function parseVirtualEntry(value) {
+    if (!value.startsWith('ress:entry?'))
+        return undefined;
+    const query = new URLSearchParams(value.slice(value.indexOf('?') + 1));
+    const pageId = query.get('page');
+    if (!pageId)
+        return undefined;
+    return { pageId, suffix: query.get('variant') ?? '' };
+}
+/**
+ * Artefactos en producción, tomados del manifest del cliente.
+ *
+ * El manifest se lee una vez al arrancar y se pasa a un índice por página y
+ * variante, de modo que servir una petición sea una consulta en memoria y no una
+ * búsqueda.
+ */
+function createProdAssetIndex(catalog, manifest, base = '/') {
+    const byPageAndVariant = new Map();
+    // El manifest indexa por el identificador de la entrada, que para un módulo
+    // virtual conserva el prefijo con el que se declaró.
+    const byEntryName = new Map();
+    for (const chunk of Object.values(manifest)) {
+        if (chunk.name)
+            byEntryName.set(chunk.name, chunk);
+    }
+    for (const entry of catalog.buildEntries) {
+        const entryName = (0, catalog_1.buildEntryNameFor)(entry.pageId, entry.variant.suffix);
+        const chunk = manifest[entry.virtualId] ??
+            manifest[NULL_BYTE + entry.virtualId] ??
+            byEntryName.get(entryName) ??
+            findByFilename(manifest, entryName);
+        if (!chunk)
+            continue;
+        byPageAndVariant.set(key(entry.pageId, entry.variant.suffix), {
+            js: joinBase(base, chunk.file),
+            css: (chunk.css ?? []).map((f) => joinBase(base, f)),
+        });
+    }
+    return { find: (pageId, variantSuffix) => byPageAndVariant.get(key(pageId, variantSuffix)) };
+}
+/** Prefijo con el que los empaquetadores marcan un módulo virtual resuelto. */
+const NULL_BYTE = String.fromCharCode(0);
+/**
+ * Respaldo por nombre de archivo.
+ *
+ * Los identificadores virtuales pueden aparecer saneados en el manifest según
+ * cómo el empaquetador normalice los caracteres del query, así que se busca
+ * además el artefacto cuyo nombre empiece por el de la entrada.
+ */
+function findByFilename(manifest, entryName) {
+    const target = entryName.replace(/[^a-zA-Z0-9_.-]/g, '_');
+    return Object.values(manifest).find((c) => {
+        const file = c.file.split('/').pop() ?? '';
+        return file.startsWith(target + '-') || file.startsWith(target + '.');
+    });
+}
+const key = (pageId, variantSuffix) => `${pageId} ${variantSuffix}`;
+function joinBase(base, file) {
+    // `/` ya es el prefijo absoluto; concatenarlo como `b + file` producía
+    // `//assets/...`, que el navegador interpreta como un host distinto. El
+    // mismo error rompía en desarrollo la URL `//@id/ress:entry...`.
+    const prefix = base === '/' ? '' : base.endsWith('/') ? base.slice(0, -1) : base;
+    return `${prefix}/${file.replace(/^\/+/, '')}`;
+}

package/dist/variants/catalog.d.ts

@@ -0,0 +1,33 @@
+import type { PageInfo } from '../pages';
+import type { VariantCatalog, PlatformRegistry } from './types';
+export interface CatalogOptions {
+    pages: PageInfo[];
+    registry?: PlatformRegistry;
+}
+/**
+ * Identificador estable de una página, compartido con el manifest de rutas.
+ *
+ * Los separadores y los corchetes de parámetro se sanean porque el identificador
+ * termina siendo el nombre de una entrada de build.
+ */
+export declare function pageIdFromFile(pageFile: string): string;
+/** Identificador del módulo virtual que hidrata esta página en esta variante. */
+export declare function virtualModuleIdFor(pageId: string, suffix: string): string;
+/**
+ * Nombre de la entrada de build de una página en una variante.
+ *
+ * El sufijo se une con `--` y sus puntos internos se vuelven guiones porque el
+ * empaquetador interpreta el ultimo punto del nombre de una entrada como su
+ * extension: con `page1__index.webview.android`, el artefacto de estilos sale
+ * como `page1__index.webview.css` y pierde el eje que lo distingue.
+ */
+export declare function buildEntryNameFor(pageId: string, suffix: string): string;
+/**
+ * Arma el catálogo: recorre las páginas y averigua qué variantes declara cada una.
+ *
+ * Corre **una sola vez** —al arrancar el servidor de desarrollo y al construir— y
+ * nunca durante una petición. Qué variantes existen lo deciden los archivos del
+ * proyecto, así que dos ejecuciones sobre el mismo árbol producen el mismo
+ * catálogo, y el build no depende de qué clientes visitaron el sitio antes.
+ */
+export declare function buildVariantCatalog(opts: CatalogOptions): Promise<VariantCatalog>;

package/dist/variants/catalog.js

@@ -0,0 +1,79 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pageIdFromFile = pageIdFromFile;
+exports.virtualModuleIdFor = virtualModuleIdFor;
+exports.buildEntryNameFor = buildEntryNameFor;
+exports.buildVariantCatalog = buildVariantCatalog;
+const module_extensions_1 = require("../fs/module-extensions");
+const platform_tokens_1 = require("./platform-tokens");
+const assets_1 = require("@ressjs/assets");
+/**
+ * Identificador estable de una página, compartido con el manifest de rutas.
+ *
+ * Los separadores y los corchetes de parámetro se sanean porque el identificador
+ * termina siendo el nombre de una entrada de build.
+ */
+function pageIdFromFile(pageFile) {
+    return pageFile
+        .replace(/^app\/pages\//, '')
+        .replace(/\.[^./]+$/, '')
+        .replace(/\//g, '__')
+        .replace(/\[([^\]]+)\]/g, '_$1_');
+}
+/** Identificador del módulo virtual que hidrata esta página en esta variante. */
+function virtualModuleIdFor(pageId, suffix) {
+    return `ress:entry?page=${pageId}&variant=${encodeURIComponent(suffix)}`;
+}
+/**
+ * Nombre de la entrada de build de una página en una variante.
+ *
+ * El sufijo se une con `--` y sus puntos internos se vuelven guiones porque el
+ * empaquetador interpreta el ultimo punto del nombre de una entrada como su
+ * extension: con `page1__index.webview.android`, el artefacto de estilos sale
+ * como `page1__index.webview.css` y pierde el eje que lo distingue.
+ */
+function buildEntryNameFor(pageId, suffix) {
+    return suffix ? `${pageId}--${suffix.replace(/\./g, '-')}` : pageId;
+}
+/**
+ * Arma el catálogo: recorre las páginas y averigua qué variantes declara cada una.
+ *
+ * Corre **una sola vez** —al arrancar el servidor de desarrollo y al construir— y
+ * nunca durante una petición. Qué variantes existen lo deciden los archivos del
+ * proyecto, así que dos ejecuciones sobre el mismo árbol producen el mismo
+ * catálogo, y el build no depende de qué clientes visitaron el sitio antes.
+ */
+async function buildVariantCatalog(opts) {
+    const registry = opts.registry ?? platform_tokens_1.defaultPlatformRegistry;
+    const buildEntries = [];
+    const variantsByPage = new Map();
+    const pagesById = new Map();
+    for (const page of opts.pages) {
+        const pageId = pageIdFromFile(page.file);
+        // La extensión la recorta el módulo canónico: los archivos de estilos de una
+        // página `.jsx` se descubren igual que los de una `.tsx`.
+        const base = (0, module_extensions_1.stripScriptExtension)(page.file);
+        const variants = (await (0, assets_1.discoverStyleVariants)(base, registry)).map((variant) => ({
+            suffix: variant.suffix,
+            tags: variant.tags,
+            styleFile: variant.sourceFile,
+        }));
+        variantsByPage.set(pageId, variants);
+        pagesById.set(pageId, { route: page.route, pageFile: page.file });
+        for (const variant of variants) {
+            buildEntries.push({
+                pageId,
+                route: page.route,
+                pageFile: page.file,
+                variant,
+                virtualId: virtualModuleIdFor(pageId, variant.suffix),
+            });
+        }
+    }
+    // Orden estable: el resultado no debe depender de cómo el sistema de archivos
+    // devuelva los nombres.
+    buildEntries.sort((a, b) => a.pageId === b.pageId
+        ? a.variant.suffix.localeCompare(b.variant.suffix)
+        : a.pageId.localeCompare(b.pageId));
+    return { buildEntries, variantsByPage, pagesById };
+}

package/dist/variants/platform-tokens.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Qué tokens de plataforma son válidos y a qué eje pertenece cada uno.
+ *
+ * El vocabulario vive en `@ressjs/platform`, que no depende del router: es la
+ * misma autoridad que consultan el puente del WebView, el cliente y la
+ * detección por petición. Tener una lista propia acá significaría que el router
+ * puede discrepar con el resto del framework sobre qué es una plataforma.
+ */
+export { createPlatformRegistry, defaultPlatformRegistry, DEFAULT_AXIS_PRECEDENCE as AXIS_PRECEDENCE, } from '@ressjs/platform';

package/dist/variants/platform-tokens.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AXIS_PRECEDENCE = exports.defaultPlatformRegistry = exports.createPlatformRegistry = void 0;
+/**
+ * Qué tokens de plataforma son válidos y a qué eje pertenece cada uno.
+ *
+ * El vocabulario vive en `@ressjs/platform`, que no depende del router: es la
+ * misma autoridad que consultan el puente del WebView, el cliente y la
+ * detección por petición. Tener una lista propia acá significaría que el router
+ * puede discrepar con el resto del framework sobre qué es una plataforma.
+ */
+var platform_1 = require("@ressjs/platform");
+Object.defineProperty(exports, "createPlatformRegistry", { enumerable: true, get: function () { return platform_1.createPlatformRegistry; } });
+Object.defineProperty(exports, "defaultPlatformRegistry", { enumerable: true, get: function () { return platform_1.defaultPlatformRegistry; } });
+Object.defineProperty(exports, "AXIS_PRECEDENCE", { enumerable: true, get: function () { return platform_1.DEFAULT_AXIS_PRECEDENCE; } });

package/dist/variants/resolve.d.ts

@@ -0,0 +1,40 @@
+import type { PlatformInfo } from '../platform';
+import type { Axis, PlatformRegistry, Variant } from './types';
+/**
+ * De todas las variantes que una página declara, cuál le toca a esta plataforma.
+ *
+ * Gana la que describe la situación con más precisión, entre las que le aplican.
+ * Para un teléfono Android dentro de un WebView, con las variantes `base`,
+ * `mobile` y `webview.android` declaradas, gana `webview.android`: las tres
+ * aplican, y esa es la que dice más sobre el cliente.
+ *
+ * Es la **única** implementación de esta decisión en el framework: la usan tanto
+ * el servidor por petición como el build. Que sea una sola es lo que impide que
+ * se construya una variante con un nombre y se busque con otro.
+ *
+ * El criterio es de especificidad y no una lista de prioridades fija, porque una
+ * lista no escala: agregar televisores o escritorio nativo obligaría a
+ * reescribirla entera y a decidir a mano dónde entra cada combinación nueva.
+ */
+export declare function resolveVariant(platform: PlatformInfo, available: Variant[], registry: PlatformRegistry): Variant;
+/**
+ * Devuelve la resolución con su explicación, para el diagnóstico de F-034 y el
+ * explorador de F-035. Un resultado inesperado sin el porqué deja en el mismo
+ * lugar que no tener nada.
+ */
+export declare function explainResolution(platform: PlatformInfo, available: Variant[], registry: PlatformRegistry): {
+    selected: Variant;
+    candidates: Array<{
+        suffix: string;
+        applies: boolean;
+        specificity: number;
+    }>;
+};
+/**
+ * Por qué ejes varía una página.
+ *
+ * Es lo que su respuesta declara en `Vary`: si todas sus variantes son la base,
+ * el documento es el mismo para cualquier cliente y no varía por nada. Si sólo
+ * distingue televisores, varía por el dispositivo y por nada más.
+ */
+export declare function varyingAxes(available: readonly Variant[]): Axis[];

package/dist/variants/resolve.js

@@ -0,0 +1,90 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveVariant = resolveVariant;
+exports.explainResolution = explainResolution;
+exports.varyingAxes = varyingAxes;
+/**
+ * De todas las variantes que una página declara, cuál le toca a esta plataforma.
+ *
+ * Gana la que describe la situación con más precisión, entre las que le aplican.
+ * Para un teléfono Android dentro de un WebView, con las variantes `base`,
+ * `mobile` y `webview.android` declaradas, gana `webview.android`: las tres
+ * aplican, y esa es la que dice más sobre el cliente.
+ *
+ * Es la **única** implementación de esta decisión en el framework: la usan tanto
+ * el servidor por petición como el build. Que sea una sola es lo que impide que
+ * se construya una variante con un nombre y se busque con otro.
+ *
+ * El criterio es de especificidad y no una lista de prioridades fija, porque una
+ * lista no escala: agregar televisores o escritorio nativo obligaría a
+ * reescribirla entera y a decidir a mano dónde entra cada combinación nueva.
+ */
+function resolveVariant(platform, available, registry) {
+    const base = available.find((v) => v.suffix === '');
+    // 1. Aplican las variantes cuyos tags matchean todos. La base no tiene tags,
+    //    así que aplica siempre.
+    const applicable = available.filter((v) => v.tags.every((tag) => registry.matches(tag, platform)));
+    if (applicable.length === 0) {
+        if (!base) {
+            throw new Error('[ress] Ninguna variante aplica y no hay variante base. ' +
+                'Toda página necesita una variante sin sufijo como respaldo.');
+        }
+        return base;
+    }
+    // 2. Gana la que describe la situación más precisa: más tags, más específica.
+    // 3. A igual cantidad, decide el eje más significativo que cada una declara.
+    return applicable.reduce((best, candidate) => compare(candidate, best, registry) > 0 ? candidate : best);
+}
+/** Positivo si `a` es más específica que `b`. */
+function compare(a, b, registry) {
+    if (a.tags.length !== b.tags.length)
+        return a.tags.length - b.tags.length;
+    // Empate de especificidad: gana la que declara el eje más significativo.
+    // `category` cambia la página más profundamente que `device`, porque un
+    // WebView embebido difiere de un navegador más de lo que un teléfono difiere
+    // de una tablet.
+    const rankA = topAxisRank(a, registry);
+    const rankB = topAxisRank(b, registry);
+    if (rankA !== rankB)
+        return rankB - rankA;
+    // Sin criterio que las distinga, el orden alfabético del sufijo mantiene el
+    // resultado estable entre ejecuciones.
+    return b.suffix.localeCompare(a.suffix);
+}
+/** Posición del eje más significativo que declara la variante. Menor es mejor. */
+function topAxisRank(v, registry) {
+    if (v.tags.length === 0)
+        return registry.axisPrecedence.length;
+    return Math.min(...v.tags.map((t) => registry.axisPrecedence.indexOf(t.axis)));
+}
+/**
+ * Devuelve la resolución con su explicación, para el diagnóstico de F-034 y el
+ * explorador de F-035. Un resultado inesperado sin el porqué deja en el mismo
+ * lugar que no tener nada.
+ */
+function explainResolution(platform, available, registry) {
+    const selected = resolveVariant(platform, available, registry);
+    return {
+        selected,
+        candidates: available.map((v) => ({
+            suffix: v.suffix,
+            applies: v.tags.every((tag) => registry.matches(tag, platform)),
+            specificity: v.tags.length,
+        })),
+    };
+}
+/**
+ * Por qué ejes varía una página.
+ *
+ * Es lo que su respuesta declara en `Vary`: si todas sus variantes son la base,
+ * el documento es el mismo para cualquier cliente y no varía por nada. Si sólo
+ * distingue televisores, varía por el dispositivo y por nada más.
+ */
+function varyingAxes(available) {
+    const axes = new Set();
+    for (const variant of available) {
+        for (const tag of variant.tags)
+            axes.add(tag.axis);
+    }
+    return [...axes];
+}

package/dist/variants/suffix.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Convierte el sufijo de un archivo de variante en tags clasificados.
+ *
+ * La implementación vive en `@ressjs/platform` junto al registro que la
+ * alimenta: separarlas dejaría que el parseo aceptara tokens que el registro no
+ * reconoce, o al revés.
+ */
+export { parseVariantSuffix } from '@ressjs/platform';

package/dist/variants/suffix.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseVariantSuffix = void 0;
+/**
+ * Convierte el sufijo de un archivo de variante en tags clasificados.
+ *
+ * La implementación vive en `@ressjs/platform` junto al registro que la
+ * alimenta: separarlas dejaría que el parseo aceptara tokens que el registro no
+ * reconoce, o al revés.
+ */
+var platform_1 = require("@ressjs/platform");
+Object.defineProperty(exports, "parseVariantSuffix", { enumerable: true, get: function () { return platform_1.parseVariantSuffix; } });