@ressjs/platform 0.6.0-experimental.0

package/dist/model/known.js

@@ -0,0 +1,9 @@
+"use strict";
+/**
+ * Vocabulario que el framework conoce de fábrica.
+ *
+ * Un proyecto puede agregar valores a los ejes `os` y `device` desde su propia
+ * configuración; lo que no puede es agregar un eje. Agregar un valor es un dato,
+ * agregar un eje es un cambio de arquitectura.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/model/types.d.ts

@@ -0,0 +1,95 @@
+import type { Axis, KnownDevice, KnownOS } from './known';
+/**
+ * Valores que un proyecto agrega a un eje.
+ *
+ * Se amplía por `declare module` desde el proyecto que consume el framework, de
+ * modo que sus tokens propios aparezcan en el autocompletado de su editor en vez
+ * de ser texto libre:
+ *
+ * ```ts
+ * declare module '@ressjs/platform' {
+ *   interface PlatformValueMap {
+ *     os: 'kaios'
+ *     device: 'watch'
+ *   }
+ * }
+ * ```
+ */
+export interface PlatformValueMap {
+}
+/** Lo que el proyecto agregó a un eje, o nada si no agregó. */
+type Extra<K extends string> = K extends keyof PlatformValueMap ? PlatformValueMap[K] : never;
+/**
+ * Unión abierta que conserva las sugerencias.
+ *
+ * `KnownOS | string` colapsa a `string` y el editor deja de sugerir nada.
+ * `KnownOS | (string & {})` no colapsa: acepta cualquier cadena y sigue
+ * ofreciendo los valores conocidos.
+ */
+type Open<Known extends string, Extra> = Known | (Extra extends string ? Extra : never) | (string & {});
+export type PlatformOS = Open<KnownOS, Extra<'os'>>;
+export type PlatformDevice = Open<KnownDevice, Extra<'device'>>;
+/** De dónde salió un campo. El orden es el de precedencia. */
+export type DetectionLayerId = 'override' | 'explicit-headers' | 'legacy-headers' | 'edge' | 'client-hints' | 'user-agent' | 'client-signals' | 'default';
+/**
+ * Cuánto se puede confiar en un campo.
+ *
+ * `exact` es el cliente diciendo lo que es; `none` es nadie habiéndolo dicho.
+ * La distinción importa: un `webview: false` por defecto no significa lo mismo
+ * que uno afirmado.
+ */
+export type Confidence = 'exact' | 'high' | 'medium' | 'low' | 'none';
+/** Procedencia de un campo individual. */
+export interface FieldOrigin {
+    layer: DetectionLayerId;
+    confidence: Confidence;
+    /** Nombre de la regla concreta que lo resolvió. Ej: `ua:tizen-smarttv`. */
+    rule?: string;
+}
+/**
+ * Datos de la app que embebe la página.
+ *
+ * Nunca participa de la resolución de variantes: qué app entró no cambia qué
+ * archivo servir. Sirve para decidir si una capacidad del puente existe en esa
+ * versión del cliente, para segmentar y para diagnosticar.
+ */
+export interface NativeAppInfo {
+    /**
+     * Identificador de la app. Ej: `com.acme.player`, `react-native`.
+     *
+     * Opcional porque el contrato v1 no tenía forma de declararlo: un cliente ya
+     * publicado manda su versión sin poder decir quién es, y descartar ese dato
+     * por un campo que su contrato no ofrecía sería perder información que el
+     * cliente sí declaró.
+     */
+    id?: string;
+    /** Versión de la app. */
+    version?: string;
+    /** Versión del sistema operativo, tal como la reporta el cliente. */
+    osVersion?: string;
+}
+/** Qué es el cliente que está del otro lado de una petición. */
+export interface PlatformInfo {
+    /** La página está incrustada dentro de una app. Su ausencia es un navegador. */
+    webview: boolean;
+    os: PlatformOS;
+    device: PlatformDevice;
+    /** Presente sólo cuando un cliente se declara. */
+    nativeApp?: NativeAppInfo;
+    /** Capacidades que el cliente declara. Ej: `['bridge','camera','dpad']`. */
+    capabilities: readonly string[];
+    detection: {
+        /** Capa de menor precedencia que aportó algún campo. */
+        source: DetectionLayerId;
+        /** La menor de las confianzas de los tres ejes. */
+        confidence: Confidence;
+        /** Qué resolvió cada eje. Esto es lo que se mira al depurar. */
+        fields: Record<Axis, FieldOrigin>;
+    };
+    /**
+     * @deprecated Modelo v1. Derivado: `headers` si algún eje vino de cabeceras,
+     * `user-agent` en cualquier otro caso.
+     */
+    source: 'headers' | 'user-agent';
+}
+export {};

package/dist/model/types.js

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

package/dist/predicates.d.ts

@@ -0,0 +1,9 @@
+import type { PlatformInfo } from './model/types';
+/** La página corre dentro de una app y no en un navegador. */
+export declare const isWebView: (p: PlatformInfo) => boolean;
+/** Pantalla grande operada con control remoto. */
+export declare const isTV: (p: PlatformInfo) => boolean;
+/** Se opera con el dedo: teléfono o tableta. */
+export declare const isHandheld: (p: PlatformInfo) => boolean;
+/** Un cliente que se identificó declara esta capacidad. */
+export declare const hasCapability: (p: PlatformInfo, capability: string) => boolean;

package/dist/predicates.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hasCapability = exports.isHandheld = exports.isTV = exports.isWebView = void 0;
+/** La página corre dentro de una app y no en un navegador. */
+const isWebView = (p) => p.webview;
+exports.isWebView = isWebView;
+/** Pantalla grande operada con control remoto. */
+const isTV = (p) => p.device === 'tv';
+exports.isTV = isTV;
+/** Se opera con el dedo: teléfono o tableta. */
+const isHandheld = (p) => p.device === 'phone' || p.device === 'tablet';
+exports.isHandheld = isHandheld;
+/** Un cliente que se identificó declara esta capacidad. */
+const hasCapability = (p, capability) => p.capabilities.includes(capability);
+exports.hasCapability = hasCapability;

package/dist/registry/create.d.ts

@@ -0,0 +1,17 @@
+import type { PlatformRegistry, RegistryOptions, UserAgentRule } from './types';
+/**
+ * Construye el registro efectivo: los valores del framework más los del proyecto.
+ *
+ * Todo se valida acá, al construir, y no en la primera petición: un token mal
+ * escrito tiene que romper el arranque, no aparecer como una variante que nunca
+ * se sirve.
+ */
+export declare function createPlatformRegistry(options?: RegistryOptions): PlatformRegistry;
+/**
+ * El registro del framework, sin extensiones.
+ *
+ * Se construye una vez por proceso: nada en él depende del proyecto, así que no
+ * hay razón para rearmarlo por cada consumidor.
+ */
+export declare const defaultPlatformRegistry: PlatformRegistry;
+export type { UserAgentRule };

package/dist/registry/create.js

@@ -0,0 +1,87 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defaultPlatformRegistry = void 0;
+exports.createPlatformRegistry = createPlatformRegistry;
+const defaults_1 = require("./defaults");
+const user_agent_1 = require("../rules/user-agent");
+/** Un token se escribe en un nombre de archivo, y el punto ya separa tokens. */
+const TOKEN_SHAPE = /^[a-z0-9][a-z0-9-]*$/;
+/**
+ * Construye el registro efectivo: los valores del framework más los del proyecto.
+ *
+ * Todo se valida acá, al construir, y no en la primera petición: un token mal
+ * escrito tiene que romper el arranque, no aparecer como una variante que nunca
+ * se sirve.
+ */
+function createPlatformRegistry(options = {}) {
+    const byToken = new Map();
+    const byAxis = new Map(defaults_1.ALL_AXES.map((axis) => [axis, []]));
+    for (const def of defaults_1.DEFAULT_VALUES)
+        register(def, byToken, byAxis, false);
+    for (const def of options.values ?? [])
+        register(def, byToken, byAxis, true);
+    const retiredByToken = new Map(defaults_1.RETIRED_TOKENS.map((def) => [def.token, def]));
+    const axisPrecedence = options.axisPrecedence
+        ? validatePrecedence(options.axisPrecedence)
+        : defaults_1.DEFAULT_AXIS_PRECEDENCE;
+    const rules = [...user_agent_1.DEFAULT_RULES, ...(options.detect ?? [])].sort((a, b) => a.priority - b.priority || a.name.localeCompare(b.name));
+    for (const [axis, values] of byAxis)
+        byAxis.set(axis, values.sort());
+    return {
+        classify: (token) => byToken.get(token),
+        matches(tag, platform) {
+            if (tag.axis === 'context')
+                return platform.webview === (tag.value === 'webview');
+            return String(platform[tag.axis]) === tag.value;
+        },
+        axisPrecedence,
+        values: (axis) => byAxis.get(axis) ?? [],
+        has: (axis, value) => byToken.get(value)?.axis === axis,
+        retired: (token) => retiredByToken.get(token),
+        rules,
+        edge: options.edge ?? [],
+    };
+}
+/**
+ * Añade un valor al índice, validando lo que un dato mal escrito puede romper.
+ *
+ * `fromProject` distingue los dos orígenes: un choque entre dos valores del
+ * framework es un error nuestro y otro mensaje que el de un proyecto intentando
+ * redefinir un token que ya existe.
+ */
+function register(def, byToken, byAxis, fromProject) {
+    if (!TOKEN_SHAPE.test(def.token)) {
+        throw new Error(`[ress] Token de plataforma inválido: "${def.token}". ` +
+            'Sólo minúsculas, dígitos y guiones, empezando por letra o dígito. ' +
+            'El punto no puede formar parte de un token porque separa tokens en el sufijo.');
+    }
+    if (!byAxis.has(def.axis)) {
+        throw new Error(`[ress] El token "${def.token}" declara el eje "${def.axis}", que no existe. ` +
+            `Ejes válidos: ${defaults_1.ALL_AXES.join(', ')}.`);
+    }
+    const existing = byToken.get(def.token);
+    if (existing) {
+        throw new Error(fromProject
+            ? `[ress] El token "${def.token}" ya existe en el registro base, en el eje ` +
+                `"${existing.axis}". Un proyecto puede agregar valores, no redefinirlos.`
+            : `[ress] El token "${def.token}" está declarado dos veces.`);
+    }
+    byToken.set(def.token, { axis: def.axis, value: def.token });
+    byAxis.get(def.axis).push(def.token);
+}
+function validatePrecedence(declared) {
+    const unique = new Set(declared);
+    const complete = unique.size === declared.length && defaults_1.ALL_AXES.every((a) => unique.has(a));
+    if (!complete) {
+        throw new Error(`[ress] axisPrecedence debe listar exactamente los ejes ${defaults_1.ALL_AXES.join(', ')}, ` +
+            `sin repetir. Se recibió: ${declared.join(', ') || '(vacío)'}.`);
+    }
+    return declared;
+}
+/**
+ * El registro del framework, sin extensiones.
+ *
+ * Se construye una vez por proceso: nada en él depende del proyecto, así que no
+ * hay razón para rearmarlo por cada consumidor.
+ */
+exports.defaultPlatformRegistry = createPlatformRegistry();

package/dist/registry/defaults.d.ts

@@ -0,0 +1,23 @@
+import type { Axis } from '../model/known';
+import type { AxisValueDef, RetiredTokenDef } from './types';
+/**
+ * Los doce tokens que el framework conoce.
+ *
+ * `unknown` no está: es el valor que toma `os` cuando nadie lo resolvió, no un
+ * token que alguien pueda escribir en un nombre de archivo.
+ */
+export declare const DEFAULT_VALUES: readonly AxisValueDef[];
+/**
+ * Tokens que el modelo tuvo y ya no tiene.
+ *
+ * Un proyecto que los usaba merece un error que explique la migración. Sin esta
+ * tabla, `index.mobile.scss` fallaría diciendo apenas que `mobile` no existe.
+ */
+export declare const RETIRED_TOKENS: readonly RetiredTokenDef[];
+/**
+ * Orden de desempate entre ejes, por selectividad: primero el que menos clientes
+ * abarca.
+ */
+export declare const DEFAULT_AXIS_PRECEDENCE: readonly Axis[];
+/** Todos los ejes del modelo, para validar una precedencia declarada por un proyecto. */
+export declare const ALL_AXES: readonly Axis[];

package/dist/registry/defaults.js

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ALL_AXES = exports.DEFAULT_AXIS_PRECEDENCE = exports.RETIRED_TOKENS = exports.DEFAULT_VALUES = void 0;
+/**
+ * Los doce tokens que el framework conoce.
+ *
+ * `unknown` no está: es el valor que toma `os` cuando nadie lo resolvió, no un
+ * token que alguien pueda escribir en un nombre de archivo.
+ */
+exports.DEFAULT_VALUES = [
+    // context — la página está incrustada en una app; su ausencia es un navegador
+    { token: 'webview', axis: 'context', label: 'Incrustada en una app' },
+    // os
+    { token: 'ios', axis: 'os', label: 'iOS y iPadOS' },
+    { token: 'android', axis: 'os', label: 'Android' },
+    { token: 'tizen', axis: 'os', label: 'Samsung Tizen' },
+    { token: 'webos', axis: 'os', label: 'LG webOS' },
+    { token: 'windows', axis: 'os', label: 'Windows' },
+    { token: 'macos', axis: 'os', label: 'macOS' },
+    { token: 'linux', axis: 'os', label: 'Linux' },
+    // device — forma del aparato y modo de operación
+    { token: 'phone', axis: 'device', label: 'Teléfono' },
+    { token: 'tablet', axis: 'device', label: 'Tableta' },
+    { token: 'tv', axis: 'device', label: 'Pantalla grande, control remoto, foco direccional' },
+    { token: 'desktop', axis: 'device', label: 'Escritorio' },
+];
+/**
+ * Tokens que el modelo tuvo y ya no tiene.
+ *
+ * Un proyecto que los usaba merece un error que explique la migración. Sin esta
+ * tabla, `index.mobile.scss` fallaría diciendo apenas que `mobile` no existe.
+ */
+exports.RETIRED_TOKENS = [
+    {
+        token: 'mobile',
+        replacement: 'phone o tablet',
+        reason: 'era un alias que aparentaba ser un dispositivo. Que dos variantes compartan ' +
+            'estilos se resuelve con un @use común, no con un token de plataforma',
+    },
+    {
+        token: 'web',
+        replacement: 'ningún token: la variante base',
+        reason: 'era el valor por defecto disfrazado de token. Un WebView también es web',
+    },
+    {
+        token: 'native',
+        replacement: 'webview, y los datos de la app llegan en nativeApp',
+        reason: 'mezclaba quién contiene la página con qué se renderiza. Si el render es nativo ' +
+            'no hay CSS, así que no puede haber variante de estilos',
+    },
+    {
+        token: 'desktop-app',
+        replacement: 'webview.desktop',
+        reason: 'una app de escritorio que muestra HTML es una página incrustada en una app',
+    },
+];
+/**
+ * Orden de desempate entre ejes, por selectividad: primero el que menos clientes
+ * abarca.
+ */
+exports.DEFAULT_AXIS_PRECEDENCE = ['context', 'os', 'device'];
+/** Todos los ejes del modelo, para validar una precedencia declarada por un proyecto. */
+exports.ALL_AXES = ['context', 'os', 'device'];

package/dist/registry/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * El registro, por separado.
+ *
+ * Quien sólo necesita saber qué tokens son válidos —una herramienta de build, un
+ * validador de nombres de archivo— importa esto y no arrastra el pipeline de
+ * detección.
+ */
+export { createPlatformRegistry, defaultPlatformRegistry } from './create';
+export { parseVariantSuffix } from './parse';
+export { ALL_AXES, DEFAULT_AXIS_PRECEDENCE, DEFAULT_VALUES, RETIRED_TOKENS, } from './defaults';
+export type { AxisValueDef, PlatformRegistry, RegistryOptions, RetiredTokenDef, RuleEffect, UserAgentRule, VariantTag, } from './types';

package/dist/registry/index.js

@@ -0,0 +1,20 @@
+"use strict";
+/**
+ * El registro, por separado.
+ *
+ * Quien sólo necesita saber qué tokens son válidos —una herramienta de build, un
+ * validador de nombres de archivo— importa esto y no arrastra el pipeline de
+ * detección.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RETIRED_TOKENS = exports.DEFAULT_VALUES = exports.DEFAULT_AXIS_PRECEDENCE = exports.ALL_AXES = exports.parseVariantSuffix = exports.defaultPlatformRegistry = exports.createPlatformRegistry = void 0;
+var create_1 = require("./create");
+Object.defineProperty(exports, "createPlatformRegistry", { enumerable: true, get: function () { return create_1.createPlatformRegistry; } });
+Object.defineProperty(exports, "defaultPlatformRegistry", { enumerable: true, get: function () { return create_1.defaultPlatformRegistry; } });
+var parse_1 = require("./parse");
+Object.defineProperty(exports, "parseVariantSuffix", { enumerable: true, get: function () { return parse_1.parseVariantSuffix; } });
+var defaults_1 = require("./defaults");
+Object.defineProperty(exports, "ALL_AXES", { enumerable: true, get: function () { return defaults_1.ALL_AXES; } });
+Object.defineProperty(exports, "DEFAULT_AXIS_PRECEDENCE", { enumerable: true, get: function () { return defaults_1.DEFAULT_AXIS_PRECEDENCE; } });
+Object.defineProperty(exports, "DEFAULT_VALUES", { enumerable: true, get: function () { return defaults_1.DEFAULT_VALUES; } });
+Object.defineProperty(exports, "RETIRED_TOKENS", { enumerable: true, get: function () { return defaults_1.RETIRED_TOKENS; } });

package/dist/registry/parse.d.ts

@@ -0,0 +1,14 @@
+import type { PlatformRegistry, VariantTag } from './types';
+/**
+ * Convierte el sufijo de un archivo de variante en tags clasificados.
+ *
+ * `index.webview.android.scss` tiene el sufijo `webview.android`, que son dos
+ * tokens de ejes distintos. El orden en que se escriben no importa: son tags, no
+ * una jerarquía, y el resultado se ordena por precedencia para que el sufijo
+ * tenga una forma canónica.
+ *
+ * Un sufijo que el registro no puede clasificar **rompe el arranque**. La
+ * alternativa —ignorar el token— produce una variante que existe en el disco y
+ * no se sirve nunca, sin ningún aviso.
+ */
+export declare function parseVariantSuffix(suffix: string, registry: PlatformRegistry, origin?: string): VariantTag[];

package/dist/registry/parse.js

@@ -0,0 +1,89 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseVariantSuffix = parseVariantSuffix;
+/**
+ * Convierte el sufijo de un archivo de variante en tags clasificados.
+ *
+ * `index.webview.android.scss` tiene el sufijo `webview.android`, que son dos
+ * tokens de ejes distintos. El orden en que se escriben no importa: son tags, no
+ * una jerarquía, y el resultado se ordena por precedencia para que el sufijo
+ * tenga una forma canónica.
+ *
+ * Un sufijo que el registro no puede clasificar **rompe el arranque**. La
+ * alternativa —ignorar el token— produce una variante que existe en el disco y
+ * no se sirve nunca, sin ningún aviso.
+ */
+function parseVariantSuffix(suffix, registry, origin) {
+    if (suffix === '')
+        return [];
+    const tags = [];
+    const seenAxes = new Map();
+    for (const token of suffix.split('.')) {
+        const tag = registry.classify(token);
+        if (!tag)
+            throw unknownToken(token, registry, origin);
+        const previous = seenAxes.get(tag.axis);
+        if (previous) {
+            throw new Error(`[ress] La variante "${suffix}"${where(origin)} pide "${previous}" y "${token}", ` +
+                `que son dos valores del eje "${tag.axis}". Una variante no puede dirigirse a ` +
+                'dos valores excluyentes del mismo eje: nunca aplicaría a ningún cliente.');
+        }
+        seenAxes.set(tag.axis, token);
+        tags.push(tag);
+    }
+    const order = registry.axisPrecedence;
+    return tags.sort((a, b) => order.indexOf(a.axis) - order.indexOf(b.axis));
+}
+/**
+ * El token no se pudo clasificar. Hay dos motivos posibles y el mensaje es
+ * distinto en cada uno: un token retirado se explica con su reemplazo, uno
+ * desconocido con la lista de válidos y la sugerencia más cercana.
+ */
+function unknownToken(token, registry, origin) {
+    const retired = registry.retired(token);
+    if (retired) {
+        return new Error(`[ress] El token de plataforma "${token}"${where(origin)} ya no existe. ` +
+            `Usá ${retired.replacement}.\n` +
+            `Se retiró porque ${retired.reason}.`);
+    }
+    const valid = allTokens(registry);
+    const suggestion = closest(token, valid);
+    return new Error(`[ress] Token de plataforma desconocido: "${token}"${where(origin)}.` +
+        (suggestion ? ` ¿Quisiste decir "${suggestion}"?` : '') +
+        `\nTokens válidos: ${valid.join(', ')}.`);
+}
+const where = (origin) => (origin ? ` en "${origin}"` : '');
+function allTokens(registry) {
+    return registry.axisPrecedence.flatMap((axis) => [...registry.values(axis)]);
+}
+/**
+ * El token válido más parecido, si hay alguno lo bastante cerca.
+ *
+ * El umbral evita sugerir cualquier cosa ante un error grosero: sugerir `tv`
+ * para `televisor` confunde más de lo que ayuda.
+ */
+function closest(token, candidates) {
+    let best;
+    let bestDistance = Math.min(3, Math.ceil(token.length / 2));
+    for (const candidate of candidates) {
+        const distance = editDistance(token, candidate);
+        if (distance <= bestDistance) {
+            bestDistance = distance;
+            best = candidate;
+        }
+    }
+    return best;
+}
+/** Distancia de Levenshtein, con una sola fila viva. */
+function editDistance(a, b) {
+    let previous = Array.from({ length: b.length + 1 }, (_, i) => i);
+    for (let i = 1; i <= a.length; i++) {
+        const current = [i];
+        for (let j = 1; j <= b.length; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            current[j] = Math.min(current[j - 1] + 1, previous[j] + 1, previous[j - 1] + cost);
+        }
+        previous = current;
+    }
+    return previous[b.length];
+}

package/dist/registry/types.d.ts

@@ -0,0 +1,91 @@
+import type { Axis } from '../model/known';
+import type { Confidence, PlatformInfo } from '../model/types';
+import type { EdgeHintRule } from '../rules/edge';
+/** Un valor válido de un eje. Es un dato, no código. */
+export interface AxisValueDef {
+    /** Token tal como se escribe en un nombre de archivo y en una cabecera. */
+    token: string;
+    axis: Axis;
+    /** Para los mensajes de error y la documentación generada. */
+    label?: string;
+}
+/**
+ * Un token que el modelo tuvo y ya no tiene.
+ *
+ * Existe para que un proyecto que lo usaba reciba un error que explique la
+ * migración, en vez de uno que diga solamente "token desconocido".
+ */
+export interface RetiredTokenDef {
+    token: string;
+    /** Qué usar en su lugar. Aparece textual en el error. */
+    replacement: string;
+    /** Por qué se retiró. Aparece textual en el error. */
+    reason: string;
+}
+/** Un token de un sufijo, ya clasificado. `android` → `{ axis: 'os', value: 'android' }`. */
+export interface VariantTag {
+    axis: Axis;
+    value: string;
+}
+/** Lo que una regla de User-Agent puede afirmar. */
+export interface RuleEffect {
+    webview?: boolean;
+    os?: string;
+    device?: string;
+}
+/**
+ * Una regla de detección por User-Agent.
+ *
+ * Las reglas son datos: se leen, se auditan y se extienden sin tocar la lógica
+ * que las recorre. `priority` define el orden y es normativo — las reglas
+ * específicas tienen que evaluarse antes que las genéricas.
+ */
+export interface UserAgentRule {
+    /** Identificador estable. Aparece en `FieldOrigin.rule`. */
+    name: string;
+    test: RegExp;
+    set: RuleEffect;
+    confidence: Confidence;
+    priority: number;
+}
+export interface PlatformRegistry {
+    /** A qué eje pertenece un token. `undefined` si el registro no lo conoce. */
+    classify(token: string): VariantTag | undefined;
+    /** ¿Este tag aplica a este cliente? */
+    matches(tag: VariantTag, platform: PlatformInfo): boolean;
+    /**
+     * Orden de desempate entre ejes cuando dos variantes son igual de específicas.
+     *
+     * El criterio es la selectividad: un eje va antes cuanto menos clientes
+     * abarca. `os` selecciona menos aparatos que `device` —iOS son iPhones y
+     * iPads, `phone` son todos los teléfonos—, así que va primero.
+     */
+    readonly axisPrecedence: readonly Axis[];
+    /** Valores válidos de un eje, ordenados. */
+    values(axis: Axis): readonly string[];
+    /** ¿Es un valor conocido de este eje? */
+    has(axis: Axis, value: string): boolean;
+    /** Si el token fue retirado, su definición. `undefined` si nunca existió. */
+    retired(token: string): RetiredTokenDef | undefined;
+    /** Reglas de User-Agent efectivas, base más las del proyecto, ya ordenadas. */
+    readonly rules: readonly UserAgentRule[];
+    /**
+     * Cabeceras que la red de distribución del proyecto calcula. Vacío por
+     * defecto: qué red hay adelante lo sabe el proyecto, no el framework.
+     */
+    readonly edge: readonly EdgeHintRule[];
+}
+/** Lo que un proyecto puede agregar al registro base. */
+export interface RegistryOptions {
+    /** Valores nuevos. No pueden redefinir un token que ya existe. */
+    values?: readonly AxisValueDef[];
+    /** Reglas propias. `priority` decide dónde se insertan en el orden. */
+    detect?: readonly UserAgentRule[];
+    /** Reordena el desempate. Debe listar exactamente los tres ejes. */
+    axisPrecedence?: readonly Axis[];
+    /**
+     * Cabeceras que calcula la red de distribución. `EDGE_PRESETS` trae
+     * definiciones listas para las conocidas; ninguna está activa de fábrica.
+     */
+    edge?: readonly EdgeHintRule[];
+}

package/dist/registry/types.js

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

package/dist/rules/apply.d.ts

@@ -0,0 +1,13 @@
+import type { PlatformRegistry } from '../registry/types';
+import type { LayerResult } from './headers';
+/**
+ * Recorre la tabla de reglas y devuelve lo que afirmaron, con salida temprana.
+ *
+ * Las reglas se evalúan en orden y **la primera que fija un campo gana**, igual
+ * que entre capas. Cuando los tres ejes ya están resueltos se corta: un
+ * User-Agent típico no llega a recorrer la tabla entera.
+ *
+ * El texto se evalúa crudo, sin pasarlo a minúsculas: las reglas que necesitan
+ * distinguir mayúsculas —`AFTB`, `CrKey`— no podrían escribirse de otro modo.
+ */
+export declare function readUserAgent(userAgent: string, registry: PlatformRegistry): LayerResult;

package/dist/rules/apply.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readUserAgent = readUserAgent;
+/**
+ * Un User-Agent más largo que esto no es un navegador: es ruido o un intento de
+ * hacer trabajar de más a las expresiones regulares.
+ */
+const MAX_LENGTH = 2048;
+/**
+ * Recorre la tabla de reglas y devuelve lo que afirmaron, con salida temprana.
+ *
+ * Las reglas se evalúan en orden y **la primera que fija un campo gana**, igual
+ * que entre capas. Cuando los tres ejes ya están resueltos se corta: un
+ * User-Agent típico no llega a recorrer la tabla entera.
+ *
+ * El texto se evalúa crudo, sin pasarlo a minúsculas: las reglas que necesitan
+ * distinguir mayúsculas —`AFTB`, `CrKey`— no podrían escribirse de otro modo.
+ */
+function readUserAgent(userAgent, registry) {
+    if (!userAgent)
+        return {};
+    const ua = userAgent.length > MAX_LENGTH ? userAgent.slice(0, MAX_LENGTH) : userAgent;
+    const result = {};
+    for (const rule of registry.rules) {
+        if (result.webview && result.os && result.device)
+            break;
+        if (!rule.test.test(ua))
+            continue;
+        if (rule.set.webview !== undefined && !result.webview) {
+            result.webview = { value: rule.set.webview, confidence: rule.confidence, rule: rule.name };
+        }
+        if (rule.set.os !== undefined && !result.os) {
+            result.os = { value: rule.set.os, confidence: rule.confidence, rule: rule.name };
+        }
+        if (rule.set.device !== undefined && !result.device) {
+            result.device = { value: rule.set.device, confidence: rule.confidence, rule: rule.name };
+        }
+    }
+    return result;
+}

package/dist/rules/edge.d.ts

@@ -0,0 +1,44 @@
+import type { Axis } from '../model/known';
+import type { Confidence } from '../model/types';
+import { type Headers, type LayerResult } from './headers';
+/**
+ * Una cabecera que la red de distribución calcula y el origen lee.
+ *
+ * Es un dato, no código: qué red hay adelante lo sabe el proyecto, no el
+ * framework. Traer un proveedor activado de fábrica ataría el framework a él y,
+ * peor, haría que todos los demás declaren en `Vary` cabeceras que nadie manda.
+ */
+export interface EdgeHintRule {
+    /** Nombre de la cabecera, en minúsculas. */
+    header: string;
+    /** A qué eje aporta. */
+    axis: Exclude<Axis, 'context'>;
+    /**
+     * Cómo se traduce su valor. La clave `'true'` cubre las cabeceras booleanas
+     * que algunas redes usan, una por tipo de dispositivo.
+     */
+    map: Record<string, string>;
+    confidence?: Confidence;
+}
+/**
+ * Definiciones listas para redes conocidas.
+ *
+ * Ninguna está activa por defecto: el proyecto declara la suya.
+ *
+ * ```ts
+ * createPlatformRegistry({ edge: EDGE_PRESETS.cloudflare })
+ * ```
+ *
+ * No hace falta un preset para funcionar. Cualquier red que sepa reescribir
+ * cabeceras —Workers, Lambda@Edge, VCL, EdgeWorkers— puede setear
+ * `x-ressjs-device` directamente, que el framework ya lee sin configurar nada y
+ * sin atarse a nadie.
+ */
+export declare const EDGE_PRESETS: Record<string, readonly EdgeHintRule[]>;
+/**
+ * Lee lo que la red ya resolvió, según las reglas que el proyecto declaró.
+ *
+ * El orden de las reglas decide: la primera que aporta un eje lo fija, igual que
+ * en el resto del pipeline.
+ */
+export declare function readEdgeHeaders(headers: Headers, rules: readonly EdgeHintRule[]): LayerResult;