@ressjs/platform 0.6.0-experimental.0 → 0.6.0-rc.1

package/LICENSE

@@ -0,0 +1,69 @@
+ress.js Proprietary License
+
+Copyright (c) 2025-2026 gabrielspisso. All rights reserved.
+
+This license applies to the ress.js packages (the "Software"), published on npm
+under the @ressjs and @gzzy scopes, in every version released from 0.6.0-rc.0
+onwards. Earlier versions were released under the MIT License and remain
+available under those terms.
+
+1. GRANT
+   Subject to this license, the Licensor grants you a worldwide, non-exclusive,
+   non-transferable, non-sublicensable, royalty-free license to install and use
+   the Software, as distributed by the Licensor, to build, run and deploy your
+   own applications and services, including commercial ones, and to charge your
+   own customers for them.
+
+2. RESTRICTIONS
+   You may not:
+   a) fork, copy, or redistribute the Software, in whole or in part, except for
+      the portions that are necessarily included in the build output of your own
+      application in order to run it;
+   b) publish, distribute or make available a modified version of the Software
+      or any work derived from it. Modifications for your own internal use are
+      allowed, but they remain subject to this license;
+   c) use the Software, or any part of it, to build, offer or support a
+      framework, library, tool or service that competes with the Software;
+   d) sell, sublicense, rent or host the Software itself as a product or service
+      for third parties, as opposed to hosting your own application built with
+      it;
+   e) remove or alter copyright, license or attribution notices;
+   f) use the name "ress.js" or the Licensor's names or marks to endorse or
+      promote your products without written permission.
+
+3. SCAFFOLDING OUTPUT
+   Files that @ressjs/create-ress-app copies into your project (templates and
+   generated configuration) are yours: you may use, modify and distribute them
+   without restriction. This does not extend to the Software packages that the
+   generated project installs as dependencies.
+
+4. SUPPORT
+   The Software is provided without any obligation of support, maintenance or
+   updates. The Licensor may offer support, maintenance, training or consulting
+   under a separate paid agreement; that agreement does not change this license
+   unless it says so explicitly and is signed by the Licensor.
+
+5. OWNERSHIP
+   The Software is licensed, not sold. The Licensor retains all rights not
+   expressly granted here. Feedback and suggestions you send may be used by the
+   Licensor without obligation to you.
+
+6. TERMINATION
+   This license ends automatically if you breach it. On termination you must
+   stop using the Software and delete your copies. Sections 4 to 8 survive
+   termination.
+
+7. NO WARRANTY
+   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+   IMPLIED, INCLUDING THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
+   PARTICULAR PURPOSE AND NON-INFRINGEMENT.
+
+8. LIMITATION OF LIABILITY
+   TO THE MAXIMUM EXTENT PERMITTED BY LAW, THE LICENSOR WILL NOT BE LIABLE FOR
+   ANY INDIRECT, INCIDENTAL, SPECIAL OR CONSEQUENTIAL DAMAGES, OR FOR LOSS OF
+   PROFITS, DATA OR BUSINESS, ARISING FROM THE USE OF OR INABILITY TO USE THE
+   SOFTWARE. THE LICENSOR'S TOTAL LIABILITY IS LIMITED TO THE AMOUNT YOU PAID
+   FOR THE SOFTWARE, WHICH MAY BE ZERO.
+
+For other uses, including exceptions to section 2, contact the Licensor to
+agree a separate license.

package/README.md

@@ -1,95 +1,23 @@
 # @ressjs/platform
 
-Responde una sola pregunta: **qué es el cliente que está del otro lado**.
+Detección de la plataforma del cliente (sistema operativo, tipo de dispositivo y si corre dentro de un WebView) para ress.js.
 
-La responden igual el router, el puente del WebView, el cliente y cualquier
-consumidor externo. Por eso vive en su propio paquete y no depende de nada.
+> Pre-release (`0.6.0-rc`). La API puede cambiar antes de `0.6.0`.
 
-```ts
-import { detect } from '@ressjs/platform'
+## Instalación
 
-const platform = detect({ userAgent, headers })
-// { webview: false, os: 'tizen', device: 'tv', ... }
+```bash
+npm install @ressjs/platform
 ```
 
-## El modelo
-
-Tres ejes ortogonales. Cualquier combinación es expresable.
-
-| Eje | Valores | Qué describe |
-|---|---|---|
-| `context` | `webview` | la página está incrustada dentro de una app; su ausencia es un navegador |
-| `os` | `ios` `android` `tizen` `webos` `windows` `macos` `linux` | sistema operativo |
-| `device` | `phone` `tablet` `tv` `desktop` | forma del aparato y modo de operación |
-
-Los datos de la app que embebe la página —cuál es, en qué versión, sobre qué
-versión del sistema— llegan en `nativeApp` y **nunca** eligen qué archivo servir.
-
-## Cómo se decide
-
-Seis capas, de lo que el cliente afirma a lo que se adivina. Cada una aporta
-sólo los campos que puede determinar, y un campo ya resuelto no se sobrescribe.
-Ninguna capa devuelve un resultado completo ni corta la evaluación: por eso
-ninguna puede volver inalcanzable a la siguiente.
-
-1. `override` — forzado para depurar, apagado salvo que se habilite
-2. `explicit-headers` — el contrato v2
-3. `legacy-headers` — el contrato v1 de los clientes ya publicados
-4. `client-hints` — lo que el navegador manda por su cuenta
-5. `user-agent` — la tabla de reglas
-6. `default` — lo que quede sin resolver
-
-Cada campo del resultado declara de qué capa salió y con cuánta confianza:
+## Uso
 
 ```ts
-platform.detection.fields.device
-// { layer: 'user-agent', confidence: 'high', rule: 'ua:android-tv' }
-```
-
-Un `webview: false` que nadie afirmó se distingue así de uno detectado.
-
-## Cabeceras
-
-| Cabecera | Aporta |
-|---|---|
-| `x-ressjs-webview` | `webview` |
-| `x-ressjs-os` | `os` |
-| `x-ressjs-device` | `device` |
-| `x-ressjs-app-id` | `nativeApp.id`, e implica `webview: true` |
-| `x-ressjs-app-version` | `nativeApp.version` |
-| `x-ressjs-os-version` | `nativeApp.osVersion` |
-| `x-ressjs-capabilities` | `capabilities`, separadas por comas |
-
-Las del contrato anterior —`x-ressjs-platform`, `x-webview`, `x-rn-platform`,
-`x-ressjs-version`— se siguen aceptando y se traducen.
-
-## Agregar una plataforma
-
-Es un dato, no un cambio de código:
+import { detect } from '@ressjs/platform'
 
-```ts
-const registry = createPlatformRegistry({
-  values: [{ token: 'kaios', axis: 'os' }],
-  detect: [
-    {
-      name: 'ua:kaios',
-      test: /KAIOS/i,
-      set: { os: 'kaios', device: 'phone' },
-      confidence: 'high',
-      priority: 150,
-    },
-  ],
-})
+const platform = detect({ userAgent, headers })
 ```
 
-A partir de ahí `index.kaios.scss` es una variante válida.
-
-## Desde el navegador
-
-```ts
-import { getPlatform } from '@ressjs/platform/client'
-```
+## Licencia
 
-Lee lo que el servidor serializó en `window.__RESS_PLATFORM__`, de modo que
-cliente y servidor coinciden exactamente. Sólo detecta por su cuenta si no hay
-nada serializado.
+Proprietary. See [LICENSE](./LICENSE).

package/dist/index.d.ts

@@ -11,7 +11,7 @@ export { detectPlatform } from './compat';
 export { DETECTION_LAYERS } from './detect/layers';
 export type { DetectionInput, DetectionLayer } from './detect/layers';
 export { createPlatformRegistry, defaultPlatformRegistry } from './registry/create';
-export { parseVariantSuffix } from './registry/parse';
+export { parseVariantSuffix, PlatformTokenError } from './registry/parse';
 export { ALL_AXES, DEFAULT_AXIS_PRECEDENCE, DEFAULT_VALUES, RETIRED_TOKENS, } from './registry/defaults';
 export { DEFAULT_RULES } from './rules/user-agent';
 export { EDGE_PRESETS, readEdgeHeaders } from './rules/edge';

package/dist/index.js

@@ -8,7 +8,7 @@
  * de nada.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.serializePlatform = exports.platformScriptTag = exports.isWebView = exports.isTV = exports.isHandheld = exports.hasCapability = exports.DEFAULT_PLATFORM = exports.varyHeadersForAxes = exports.HEADERS_BY_AXIS = exports.PLATFORM_VARY_HEADERS = exports.PLATFORM_REQUEST_HEADERS = exports.HEADERS_V2 = exports.HEADERS_LEGACY = exports.HEADERS_CLIENT_HINTS = exports.HEADER_OVERRIDE = exports.readEdgeHeaders = exports.EDGE_PRESETS = exports.DEFAULT_RULES = exports.RETIRED_TOKENS = exports.DEFAULT_VALUES = exports.DEFAULT_AXIS_PRECEDENCE = exports.ALL_AXES = exports.parseVariantSuffix = exports.defaultPlatformRegistry = exports.createPlatformRegistry = exports.DETECTION_LAYERS = exports.detectPlatform = exports.detect = void 0;
+exports.serializePlatform = exports.platformScriptTag = exports.isWebView = exports.isTV = exports.isHandheld = exports.hasCapability = exports.DEFAULT_PLATFORM = exports.varyHeadersForAxes = exports.HEADERS_BY_AXIS = exports.PLATFORM_VARY_HEADERS = exports.PLATFORM_REQUEST_HEADERS = exports.HEADERS_V2 = exports.HEADERS_LEGACY = exports.HEADERS_CLIENT_HINTS = exports.HEADER_OVERRIDE = exports.readEdgeHeaders = exports.EDGE_PRESETS = exports.DEFAULT_RULES = exports.RETIRED_TOKENS = exports.DEFAULT_VALUES = exports.DEFAULT_AXIS_PRECEDENCE = exports.ALL_AXES = exports.PlatformTokenError = exports.parseVariantSuffix = exports.defaultPlatformRegistry = exports.createPlatformRegistry = exports.DETECTION_LAYERS = exports.detectPlatform = exports.detect = void 0;
 var pipeline_1 = require("./detect/pipeline");
 Object.defineProperty(exports, "detect", { enumerable: true, get: function () { return pipeline_1.detect; } });
 var compat_1 = require("./compat");
@@ -20,6 +20,7 @@ Object.defineProperty(exports, "createPlatformRegistry", { enumerable: true, get
 Object.defineProperty(exports, "defaultPlatformRegistry", { enumerable: true, get: function () { return create_1.defaultPlatformRegistry; } });
 var parse_1 = require("./registry/parse");
 Object.defineProperty(exports, "parseVariantSuffix", { enumerable: true, get: function () { return parse_1.parseVariantSuffix; } });
+Object.defineProperty(exports, "PlatformTokenError", { enumerable: true, get: function () { return parse_1.PlatformTokenError; } });
 var defaults_1 = require("./registry/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; } });

package/dist/registry/parse.d.ts

@@ -1,4 +1,32 @@
 import type { PlatformRegistry, VariantTag } from './types';
+/**
+ * Un token de plataforma del nombre de un archivo no se pudo clasificar.
+ *
+ * Lleva los datos además del texto, para que quien lo muestre (la CLI) pueda
+ * darle el formato de sus demás errores sin interpretar el mensaje.
+ */
+export declare class PlatformTokenError extends Error {
+    /** Estable: lo reconocen quienes no pueden importar esta clase. */
+    readonly code: "RESS_PLATFORM_TOKEN";
+    readonly kind: 'retired' | 'unknown';
+    readonly token: string;
+    readonly origin?: string;
+    /** Sólo `retired`: con qué se reemplaza y por qué se retiró. */
+    readonly replacement?: string;
+    readonly reason?: string;
+    /** Sólo `unknown`: el token válido más parecido. */
+    readonly suggestion?: string;
+    readonly valid: readonly string[];
+    constructor(message: string, details: {
+        kind: 'retired' | 'unknown';
+        token: string;
+        origin?: string;
+        replacement?: string;
+        reason?: string;
+        suggestion?: string;
+        valid: readonly string[];
+    });
+}
 /**
  * Convierte el sufijo de un archivo de variante en tags clasificados.
  *

package/dist/registry/parse.js

@@ -1,6 +1,38 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.PlatformTokenError = void 0;
 exports.parseVariantSuffix = parseVariantSuffix;
+/**
+ * Un token de plataforma del nombre de un archivo no se pudo clasificar.
+ *
+ * Lleva los datos además del texto, para que quien lo muestre (la CLI) pueda
+ * darle el formato de sus demás errores sin interpretar el mensaje.
+ */
+class PlatformTokenError extends Error {
+    /** Estable: lo reconocen quienes no pueden importar esta clase. */
+    code = 'RESS_PLATFORM_TOKEN';
+    kind;
+    token;
+    origin;
+    /** Sólo `retired`: con qué se reemplaza y por qué se retiró. */
+    replacement;
+    reason;
+    /** Sólo `unknown`: el token válido más parecido. */
+    suggestion;
+    valid;
+    constructor(message, details) {
+        super(message);
+        this.name = 'PlatformTokenError';
+        this.kind = details.kind;
+        this.token = details.token;
+        this.origin = details.origin;
+        this.replacement = details.replacement;
+        this.reason = details.reason;
+        this.suggestion = details.suggestion;
+        this.valid = details.valid;
+    }
+}
+exports.PlatformTokenError = PlatformTokenError;
 /**
  * Convierte el sufijo de un archivo de variante en tags clasificados.
  *
@@ -40,17 +72,17 @@ function parseVariantSuffix(suffix, registry, origin) {
  * desconocido con la lista de válidos y la sugerencia más cercana.
  */
 function unknownToken(token, registry, origin) {
+    const valid = allTokens(registry);
     const retired = registry.retired(token);
     if (retired) {
-        return new Error(`[ress] El token de plataforma "${token}"${where(origin)} ya no existe. ` +
+        return new PlatformTokenError(`[ress] El token de plataforma "${token}"${where(origin)} ya no existe. ` +
             `Usá ${retired.replacement}.\n` +
-            `Se retiró porque ${retired.reason}.`);
+            `Se retiró porque ${retired.reason}.`, { kind: 'retired', token, origin, replacement: retired.replacement, reason: retired.reason, valid });
     }
-    const valid = allTokens(registry);
     const suggestion = closest(token, valid);
-    return new Error(`[ress] Token de plataforma desconocido: "${token}"${where(origin)}.` +
+    return new PlatformTokenError(`[ress] Token de plataforma desconocido: "${token}"${where(origin)}.` +
         (suggestion ? ` ¿Quisiste decir "${suggestion}"?` : '') +
-        `\nTokens válidos: ${valid.join(', ')}.`);
+        `\nTokens válidos: ${valid.join(', ')}.`, { kind: 'unknown', token, origin, suggestion, valid });
 }
 const where = (origin) => (origin ? ` en "${origin}"` : '');
 function allTokens(registry) {

package/dist/rules/request-headers.d.ts

@@ -43,12 +43,13 @@ export declare const HEADERS_BY_AXIS: {
 /**
  * Las cabeceras a declarar para una respuesta que varía por estos ejes.
  *
- * `User-Agent` afecta a los tres y se lista primero: es el de mayor cardinalidad
- * y el que conviene normalizar en el borde. Sin ejes, la lista es vacía — y una
- * respuesta que no varía por nada no debe declarar `Vary`.
+ * Nunca incluye `User-Agent`: la detección lo usa para resolver (R-10), pero
+ * tiene tantos valores que una caché que separe por él casi nunca acierta. No
+ * declararlo es una política: lo que depende de la plataforma no se declara
+ * compartible (`security/headers.ts` en vite-router). Sin ejes, la lista es
+ * vacía — y una respuesta que no varía por nada no debe declarar `Vary`.
  */
 export declare function varyHeadersForAxes(axes: readonly ('context' | 'os' | 'device')[], options?: {
-    includeUserAgent?: boolean;
     /**
      * Cabeceras que el proyecto declaró para su red de distribución. Se suman
      * porque también cambian la respuesta; si no declaró ninguna, no aparece

package/dist/rules/request-headers.js

@@ -91,16 +91,16 @@ exports.HEADERS_BY_AXIS = {
 /**
  * Las cabeceras a declarar para una respuesta que varía por estos ejes.
  *
- * `User-Agent` afecta a los tres y se lista primero: es el de mayor cardinalidad
- * y el que conviene normalizar en el borde. Sin ejes, la lista es vacía — y una
- * respuesta que no varía por nada no debe declarar `Vary`.
+ * Nunca incluye `User-Agent`: la detección lo usa para resolver (R-10), pero
+ * tiene tantos valores que una caché que separe por él casi nunca acierta. No
+ * declararlo es una política: lo que depende de la plataforma no se declara
+ * compartible (`security/headers.ts` en vite-router). Sin ejes, la lista es
+ * vacía — y una respuesta que no varía por nada no debe declarar `Vary`.
  */
 function varyHeadersForAxes(axes, options = {}) {
     if (axes.length === 0)
         return [];
     const fields = new Set();
-    if (options.includeUserAgent ?? true)
-        fields.add('User-Agent');
     for (const axis of axes) {
         for (const header of exports.HEADERS_BY_AXIS[axis])
             fields.add(header);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ressjs/platform",
-  "version": "0.6.0-experimental.0",
+  "version": "0.6.0-rc.1",
   "description": "Modelo de plataforma de ress.js: registro de tokens y detección del cliente. Sin dependencias.",
   "types": "dist/index.d.ts",
   "main": "dist/index.js",
@@ -40,7 +40,7 @@
     "tv",
     "ressjs"
   ],
-  "license": "MIT",
+  "license": "SEE LICENSE IN LICENSE",
   "devDependencies": {
     "typescript": "^5.9.3",
     "vitest": "^3.2.4"