@nitida/asset-client 0.16.2 → 0.16.4

package/src/palette.ts

@@ -100,8 +100,8 @@ export function relativeLuminance(hex: string): number {
 }
 
 /**
- * Razón de contraste WCAG entre dos luminancias: `(L1 + 0.05) / (L2 + 0.05)`,
- * con la más clara arriba. 1 = idénticos, 21 = negro contra blanco.
+ * WCAG contrast ratio between two luminances: `(L1 + 0.05) / (L2 + 0.05)`,
+ * lighter on top. 1 = identical, 21 = black against white.
  */
 export function contrastRatio(l1: number, l2: number): number {
   const [hi, lo] = l1 >= l2 ? [l1, l2] : [l2, l1];
@@ -109,37 +109,38 @@ export function contrastRatio(l1: number, l2: number): number {
 }
 
 /**
- * Negro o blanco, el que **de verdad** contraste más sobre este fondo.
+ * Black or white — whichever **actually** contrasts more against this
+ * background.
  *
- * ⚠️ CORREGIDO 2026-08-17. Antes decidía con `L > 0.5`, y **0,5 no es el punto
- * de empate**. Igualando las dos razones de contraste:
+ * The tie point is NOT `L > 0.5`, which is the threshold most implementations
+ * reach for. Equating the two contrast ratios gives it exactly:
  *
  *     (1 + 0.05) / (L + 0.05)  =  (L + 0.05) / 0.05
  *     (L + 0.05)²              =  0.0525
  *     L                        =  0.1791…
  *
- * Entre **0,179 y 0,5** el código viejo elegía BLANCO cuando negro contrastaba
- * más — una banda ancha, y justo donde caen los colores de marca saturados.
- * Medido sobre cuatro paletas reales de producción: **8 swatches** en esa banda.
- * El peor, el dorado dominante `#CA9528`: devolvía blanco a **2,68:1** cuando
- * negro da **7,84:1**. 2,68 no pasa AA ni para texto grande.
+ * Between **0.179 and 0.5** a `L > 0.5` test picks WHITE while black contrasts
+ * more — a wide band, and exactly where saturated brand colours land. A
+ * mid-luminance gold in that band can be handed white at **2.68:1** when black
+ * would give **7.84:1**; 2.68 does not pass AA even for large text.
  *
- * No se cambia el umbral por 0,179: se **calculan las dos razones y gana la
- * mayor**. Un umbral es una constante que hay que mantener correcta; la
- * comparación es correcta por construcción.
+ * So this does not swap one threshold for another: it **computes both ratios
+ * and returns the winner**. A threshold is a constant somebody has to keep
+ * correct; the comparison is correct by construction.
  *
- * ⚠️ Esto elige el MEJOR de dos, no garantiza que alcance. Sobre un fondo de
- * luminancia media el mejor par puede quedar por debajo de 4,5:1 igual — para
- * eso está {@link bestTextContrast}, que además devuelve el número.
+ * ⚠️ This picks the BETTER of two — it does not guarantee the result is
+ * enough. Over a mid-luminance background the best pair can still land under
+ * 4.5:1. Use {@link bestTextContrast} when you need to know: it returns the
+ * ratio it achieved.
  */
 function textColorForHex(hex: string): "#000000" | "#FFFFFF" {
   return bestTextContrast(hex).color;
 }
 
 /**
- * Igual que el color recomendado, pero devuelve también **la razón lograda** y
- * si pasa AA — para que quien lo use pueda decidir con el número a la vista en
- * vez de asumir que alcanzó.
+ * Same choice as the recommended text colour, but it also returns **the ratio
+ * it achieved** and whether that passes AA — so a caller can decide with the
+ * number in front of them instead of assuming it was enough.
  */
 export function bestTextContrast(hex: string): {
   color: "#000000" | "#FFFFFF";

package/src/slots.ts

@@ -4,9 +4,9 @@
  * Slots give tenants a way to attach stable, human-readable names
  * ("webapp.wizard.pool-type.icon-1", "storefront.cr.hero-video.landscape_hd_16x9.mp4")
  * to assets they uploaded. Consumers resolve names → AssetDTOs at
- * build / runtime so their source never hardcodes a CDN URL; the
- * admin rebinds a slot from `asset-lab-web` and every consumer picks
- * up the swap on cache refresh.
+ * build / runtime so their source never hardcodes a CDN URL; an
+ * admin rebinds a slot in the platform console and every consumer
+ * picks up the swap on cache refresh.
  *
  * Two layers in this package:
  *   - `resolveSlot` / `resolveSlots` — universal (server, edge,
@@ -67,8 +67,8 @@ let tenantCode: string | null = null;
  *
  *   configureSlotResolver({
  *     endpoint: process.env.AQUIENPZ_URL,
- *     apiKey:   process.env.ASSET_MANAGER_RUNTIME_KEY,
- *     tenantCode: "realtyone-cr",
+ *     apiKey:   process.env.AQUIENPZ_API_KEY,   // amk_rt_* — server-only
+ *     tenantCode: "acme-co",
  *   });
  */
 export function configureSlotResolver(opts: {

package/src/transform.ts

@@ -262,13 +262,28 @@ export function getVideoTransformUrl(
  * if (prefersNativeHls(video)) {
  *   video.src = src;
  * } else {
- *   // Defaults open at a fixed low rung — measure instead of guessing.
- *   const hls = new Hls({ startLevel: -1, testBandwidth: true, abrEwmaDefaultEstimate: 1_000_000 });
+ *   const hls = new Hls({ capLevelToPlayerSize: false, abrEwmaDefaultEstimate: 5_000_000 });
  *   hls.loadSource(src);
  *   hls.attachMedia(video);
  * }
  * ```
  *
+ * ⚠️ **Do NOT pass `startLevel: -1` with `testBandwidth: true`.** That pair is
+ * documented by hls.js as *"forces the player to download a fragment from the
+ * lowest level to establish a bandwidth estimate"* — on a clip short enough to
+ * be one segment, the probe IS the whole video, and it plays at the bottom
+ * rung from first frame to last. (This doc-comment recommended exactly that
+ * until 2026-08-18; a 5.042 s 4K asset was measured being delivered at
+ * 426x240 because of it.) Leave `startLevel` unset: hls.js then opens on the
+ * FIRST level in the manifest, and the server puts the right one there —
+ * a mid rung for long video, the top rung for a clip under 18 s, which is the
+ * same rung native HLS opens on per RFC 8216 §6.3.4. The ladder decides; the
+ * player should not second-guess it.
+ *
+ * `capLevelToPlayerSize` is worth disabling explicitly: `@videojs/core`
+ * defaults it to `true`, which caps quality to the player's rendered pixel box,
+ * so a small inline player is pinned to 240p/360p on any connection.
+ *
  * On first request the server returns 202 Accepted while a background
  * job transcodes the ladder (typically 1-3 min for a 90 s source);
  * subsequent requests get 302 to the cached master.m3u8. Keep the