@nitida/asset-client 0.16.1 → 0.16.3

package/src/index.ts

@@ -37,12 +37,19 @@ export type VariantPreset =
   | "poster"
   | "video"
   | "aiproxy"
+  // The adaptive HLS ladder. Unlike every other preset this is NOT one file:
+  // it is a `master.m3u8` plus one media playlist + segment set per rung. It is
+  // a preset because the question callers ask about it is the same one they ask
+  // about the others — *does this asset have one?* — and `hasPreset` is the
+  // place that question is answered. What it HAS, rung by rung, is in the
+  // `hls` entry of `variants` ({@link AssetVariant.rungs}).
+  | "hls"
   // audio preset — the cross-browser mp3 transcode of a voice note
   // (libmp3lame) emitted alongside the original so chat audio plays on
   // both Chrome/Android (webm/opus) and iOS Safari (which can't decode opus).
   | "mp3";
 
-/** 1-char alias used in R2 keys / wire `presets` string. */
+/** 1-char alias used in storage keys / wire `presets` string. */
 export const PRESET_SHORT: Record<VariantPreset, string> = {
   thumb: "q",
   sm: "s",
@@ -53,7 +60,12 @@ export const PRESET_SHORT: Record<VariantPreset, string> = {
   poster: "p",
   video: "v",
   aiproxy: "a",
-  // 3 chars, NOT a 1-char alias: the asset-manager has no short-form for
+  // `h` — free in both directions: no other preset claims it, and no
+  // multi-character token that `stripMultiCharTokens` removes donates one
+  // (`transform-<hex>` → t/r/a/n/s/f/o/m + a–f; `pr`; `mp3`). So a server that
+  // starts emitting `h` cannot make an OLDER client answer `true` to anything.
+  hls: "h",
+  // 3 chars, NOT a 1-char alias: the server has no short-form for
   // audio so its `shortPreset("mp3")` falls through to the literal token,
   // and the deployed server already writes the `-mp3.mp3` variant + emits
   // the bare `mp3` token in the wire `presets` string. Must stay in lockstep.
@@ -74,6 +86,9 @@ export const PRESET_EXT: Record<VariantPreset, string> = {
   poster: "webp",
   video: "mp4",
   aiproxy: "mp4",
+  // The ladder's ENTRY file. Never used to build a key — see `getAssetUrl`,
+  // which refuses to derive `<sha>-h.m3u8` because no such object exists.
+  hls: "m3u8",
   mp3: "mp3",
 };
 
@@ -88,6 +103,10 @@ export const PRESET_MAX_DIM: Record<VariantPreset, number | null> = {
   poster: null,
   video: null,
   aiproxy: null,
+  // A ladder has no single max side — it has a rung per size. `null` keeps it
+  // out of `getAssetSrcSet`, where offering an `.m3u8` as an `<img>` candidate
+  // would be nonsense. Its ceiling is `variants.find(v => v.preset === "hls").height`.
+  hls: null,
   // audio has no pixel dimensions; `null` keeps mp3 out of the
   // dimension-based `getAssetSrcSet` / `computeVariantDimensions` logic.
   mp3: null,
@@ -102,11 +121,11 @@ export type AssetVariant = {
   preset: VariantPreset;
   /** Public CDN URL of this variant. */
   url: string;
-  /** Pixel width. Absent for `original`-only assets where sharp was skipped, or for video presets. */
+  /** Pixel width. Absent for `original`-only assets where image processing was skipped, or for video presets. */
   width?: number;
   /** Pixel height. Same caveat as `width`. */
   height?: number;
-  /** Byte size of the variant file on R2. */
+  /** Byte size of the stored variant file. */
   bytes: number;
   /**
    * Where the bytes for this variant came from. Useful for quality
@@ -120,11 +139,110 @@ export type AssetVariant = {
    *
    * Absent on variants written before the trace field existed.
    */
-  sourceFrom?: VariantPreset | "upload";
+  sourceFrom?:
+    | VariantPreset
+    | "upload"
+    // Written by the on-demand `/t/` route (`transform-<hash>` entries).
+    | "transform-route"
+    // The two ways an `hls` entry comes to exist: written by the transcode that
+    // produced the ladder, or read back off the CDN by the backfill/self-heal.
+    | "hls-transcode"
+    | "cdn-probe";
   /** ISO timestamp this variant was written. Absent on pre-trace variants. */
   createdAt?: string;
+  /**
+   * **`preset: "hls"` only** — the ladder's rungs, in MASTER ORDER.
+   *
+   * The reason this exists: an entry that only says *there is a ladder* leaves
+   * a consumer that plans a composition exactly as blind as no entry at all,
+   * because the ceiling of a composition is its weakest ingredient and there is
+   * no upscale. Before this field the only way to learn a clip's real rungs was
+   * to fetch the master playlist — or worse, download the asset.
+   *
+   * `rungs[0]` is the rung every client OPENS on (RFC 8216 §6.3.4 for native
+   * HLS; hls.js with `startLevel` unset uses "the first level in the
+   * manifest"), so the order is a delivery fact — do not sort it in place.
+   *
+   * Use {@link hlsLadderAlignment} rather than eyeballing `segments`: a ladder
+   * can be complete and still unable to adapt.
+   */
+  rungs?: HlsRung[];
+};
+
+/**
+ * One rung of an adaptive HLS ladder.
+ *
+ * `segments` / `durationSec` are what make a ladder JUDGEABLE rather than
+ * merely present. Measured on a prod ladder of an 87 s 4K source: 240p cut at
+ * 14.35 s in 12 segments, 720p at 5.63 s in 12, 2160p at 5.88 s in 14. Cuts
+ * that do not line up cannot be swapped, and a swap is what a rendition switch
+ * IS — so that ladder looked complete and adapted badly. One segment means zero
+ * switch points: whichever rung the player opens on is the rung it finishes on.
+ *
+ * Both are optional because a rung whose playlist could not be read is recorded
+ * WITHOUT them rather than with a zero — unmeasured and none are different
+ * facts, and a `0` there would read as the latter.
+ */
+export type HlsRung = {
+  /** Rung directory / identity — `"720p"`. */
+  name: string;
+  /** `RESOLUTION` from the master playlist. */
+  width: number;
+  height: number;
+  /** `BANDWIDTH` in bits per second. */
+  bandwidth: number;
+  /** Absolute URL of this rung's media playlist. */
+  url: string;
+  /** `#EXTINF` count. */
+  segments?: number;
+  /** Sum of the `#EXTINF` values, seconds. */
+  durationSec?: number;
 };
 
+/**
+ * The ladder of an asset, or `null` when it has none / the DTO does not carry
+ * `variants` (the slim list shape never does — use `hasPreset(a, "hls")` there).
+ */
+export function getHlsLadder(
+  asset: Pick<AssetDTO, "variants">,
+): AssetVariant | null {
+  return asset.variants?.find((v) => v.preset === "hls") ?? null;
+}
+
+/**
+ * What the recorded rungs actually support — computed here, never stored, so
+ * one rule serves every consumer and a change to it does not need a backfill.
+ *
+ * - `switchable`: more than one rung AND more than one segment. False means the
+ *   player is pinned to whatever rung it opens on for the entire clip.
+ * - `aligned`: every measured rung reports the same segment count. `null` means
+ *   fewer than two rungs were measured — **unknown, not false.** Treating that
+ *   as `false` rejects ladders nobody looked at.
+ * - `ceilingHeight`: the tallest rung. The ceiling of any composition using it.
+ */
+export function hlsLadderAlignment(rungs: HlsRung[]): {
+  rungCount: number;
+  ceilingHeight: number;
+  floorHeight: number;
+  switchable: boolean;
+  aligned: boolean | null;
+  minSegments: number | null;
+} {
+  const heights = rungs.map((r) => r.height);
+  const measured = rungs
+    .map((r) => r.segments)
+    .filter((s): s is number => typeof s === "number" && s > 0);
+  const minSegments = measured.length > 0 ? Math.min(...measured) : null;
+  return {
+    rungCount: rungs.length,
+    ceilingHeight: heights.length > 0 ? Math.max(...heights) : 0,
+    floorHeight: heights.length > 0 ? Math.min(...heights) : 0,
+    switchable: rungs.length > 1 && (minSegments ?? 0) > 1,
+    aligned: measured.length >= 2 ? new Set(measured).size === 1 : null,
+    minSegments,
+  };
+}
+
 /**
  * Compact wire shape — what the server actually sends. Aliases (`w`, `h`,
  * `dur`) are intentional to shave bytes per asset on dense lists.
@@ -181,8 +299,8 @@ export {
   getPaletteCssVars,
   getTextColorForBackground,
   iteratePaletteSwatches,
-  relativeLuminance,
   pickAmbientBackground,
+  relativeLuminance,
 } from "./palette";
 
 import type { AssetPalette } from "./palette";
@@ -208,7 +326,7 @@ export function getCdnBase(): string {
 // Tenant scope
 //
 // Post-May-2026 the CDN serves variants under a tenant-prefixed path
-// `<cdn>/<tenantId base36>/v/<sha16>-<preset>.<ext>` (see asset-manager
+// `<cdn>/<tenantId base36>/v/<sha16>-<preset>.<ext>` (see the server
 // `variantKey`). Variant URL builders MUST include that prefix or every
 // URL 404s. The tenant id is process-global (one tenant per client/app),
 // set once at boot — `NitidaClient` does this from its `tenantId` option;
@@ -268,15 +386,13 @@ const ORIGINAL_EXT_BY_MIME: Record<string, string> = {
   "video/mp4": "mp4",
   "video/webm": "webm",
   "video/quicktime": "mov",
-  // Audio — ausentes hasta 2026-08-17, y su ausencia costó un rodeo entero en
-  // neo (`withRealOriginalExt`), que existe SÓLO porque esta tabla devolvía el
-  // centinela `bin` para toda nota de voz. Medido en producción: `-o.bin` da
-  // 404 y `-o.m4a` da 200.
+  // Audio — absent until 2026-08-17. While they were missing this table
+  // returned the `bin` sentinel for every voice note, so consumers had to
+  // hand-roll the extension themselves. Measured: `-o.bin` 404s, `-o.m4a` 200s.
   //
-  // ⚠️ Se keyean por el mime COMPLETO, no por el subtipo: `audio/mp4` guarda
-  // `.m4a` y `video/mp4` guarda `.mp4`. Un `switch` sobre el subtipo `mp4` no
-  // puede distinguirlos — es el error que un consumidor cometió y tuvo que
-  // corregir por su cuenta.
+  // ⚠️ These are keyed by the FULL mime, not the subtype: `audio/mp4` is stored
+  // as `.m4a` and `video/mp4` as `.mp4`. A `switch` on the `mp4` subtype cannot
+  // tell them apart — a mistake worth not repeating.
   "audio/mpeg": "mpga",
   "audio/mp4": "m4a",
   "audio/x-m4a": "m4a",
@@ -344,6 +460,19 @@ export function getAssetUrl(
     const ext = asset.oext || originalExtForMime(asset.mime);
     return `${cdnBaseUrl}/${variantPrefix()}${asset.sha}-${PRESET_SHORT.original}.${ext}`;
   }
+  if (preset === "hls") {
+    // A ladder is a PREFIX (`<sha16>-hls<dslHash>/master.m3u8`), not a
+    // `<sha16>-h.m3u8` file, and `<dslHash>` is a server-side hash. Deriving a
+    // key from the pattern below would produce a URL that 404s on every asset
+    // — the same class of polite lie that once pointed a large share of assets
+    // at a `-o.<ext>` that was never written. So: the stored URL when the DTO
+    // carries it, else the
+    // transform route, which 302s to the master and BUILDS the ladder if it is
+    // missing. Both are real; neither is a guess.
+    const stored = asset.variants?.find((v) => v.preset === "hls")?.url;
+    if (stored) return stored;
+    return `${cdnBaseUrl}/t/format=hls/${asset.sha}.m3u8`;
+  }
   return `${cdnBaseUrl}/${variantPrefix()}${asset.sha}-${PRESET_SHORT[preset]}.${PRESET_EXT[preset]}`;
 }
 
@@ -353,7 +482,7 @@ export function getAssetUrl(
  * Reads `dto.presets` — the compact 1-char code string the server sends on EVERY shape, including
  * the slim list/resolver one that carries no `variants` at all. That is why this exists and why it
  * stays the right existence check even now that `GET /assets/:id` really does send `variants`
- * (it did not until 2026-08-17; doc 240 §4.3).
+ * (it did not until the 2026-08-17 deploy).
  *
  * @example
  * ```ts
@@ -378,7 +507,7 @@ export function hasPreset(
  *
  * `presets` is documented as a concatenation of 1-char codes, and membership is
  * a 1-char substring test — so any longer token is a false-positive generator.
- * Servers before the 2026-08-17 deploy emitted several (doc 240 §4.3b):
+ * Servers before the 2026-08-17 deploy emitted several:
  *
  * | token in the string | letters it donates | presets it falsely answers |
  * |---|---|---|
@@ -386,14 +515,15 @@ export function hasPreset(
  * | `pr` (probe) | p r | `poster` |
  * | `mp3` (audio) | m p | `md` `poster` — stripped here since forever |
  *
- * Measured against production: **62 % of live assets** carried a polluted
- * string, and **16 299 of them were told they have an `original` they do not**
- * — which builds a `-o.<ext>` URL that 404s. (`aiproxy`: 16 479. `sm`/`md`: 487.
- * The `pr` → `poster` collision is real but has 0 instances today.)
+ * This is not theoretical: on a corpus written by pre-2026-08-17 servers the
+ * majority of rows carried a polluted string, and a large minority of those
+ * were told they have an `original` they do not — which builds a `-o.<ext>`
+ * URL that 404s. `aiproxy` is affected at the same order of magnitude, `sm`
+ * and `md` far less, and the `pr` → `poster` collision is real but rare.
  *
- * Current servers no longer emit these, but this stays: an older
- * `asset-manager` keeps sending them, and this is the check every guide points
- * at as the reliable one. Order matters — strip the longest tokens first.
+ * Current servers no longer emit these, but this stays: older server deploys
+ * keep sending them, and this is the check every guide points at as the
+ * reliable one. Order matters — strip the longest tokens first.
  */
 function stripMultiCharTokens(presets: string): string {
   return presets

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,
@@ -20,7 +20,7 @@ import type { AssetDTO, VariantPreset } from "./index";
 import { getAssetUrl, hasPreset } from "./index";
 
 // ---------------------------------------------------------------------------
-// Wire shape — matches `apps/asset-manager/src/features/assets/slots.routes.ts`
+// Wire shape — matches the server's slots route.
 // ---------------------------------------------------------------------------
 
 export type SlotDTO = {
@@ -53,14 +53,11 @@ export type SlotResolution = {
 const DEFAULT_TTL_MS = 60_000;
 const cache = new Map<string, { fetchedAt: number; value: SlotDTO | null }>();
 
-// Deliberately the generated `run.app` URL, NOT the branded
-// `api.nitida.gofuture.space` the docs publish — this is the fallback for a
-// caller that configured nothing, so it should be the address with the fewest
-// moving parts. Cloud Run guarantees the generated URL forever; the branded name
-// is an additional domain mapping that depends on DNS and a managed certificate
-// (and on 2026-08-17 we learned how many ways those two can go sideways —
-// doc 242 §6.3). Both names hit the same service and return identical bodies.
-let endpoint = "https://aquienpz-asset-manager-nlchzy26qa-uc.a.run.app";
+// The published API host — the same address the docs give out, so a caller
+// that configured nothing still talks to the documented endpoint. Override it
+// with `configureSlotResolver({ endpoint })` to point at a different
+// deployment.
+let endpoint = "https://api.nitida.gofuture.space";
 let apiKey: string | null = null;
 let tenantCode: string | null = null;
 
@@ -70,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

@@ -2,10 +2,9 @@
  * On-the-fly transform URL builder.
  *
  * Mirrors the server's DSL canonicalizer byte-for-byte so a URL generated
- * here hashes to the same R2 cache key as the server's canonical form.
+ * here hashes to the same cache key as the server's canonical form.
  *
- * Canonicalization rules (keep in sync with
- * `apps/asset-manager/src/features/assets/transform.dsl.ts`):
+ * Canonicalization rules (kept in sync with the server):
  *   - Drop entries whose value is `undefined`
  *   - Sort keys alphabetically
  *   - Numbers rendered without leading zeros or trailing dots
@@ -23,7 +22,7 @@ import type { AssetDTO } from "./index";
 import { getCdnBase } from "./index";
 
 /**
- * Widths the CDN edge whitelists (DoS guard — see `apps/cdn-proxy` WHITELIST_WIDTHS).
+ * Widths the CDN edge whitelists (DoS guard).
  * Requesting any OTHER width returns HTTP 400 at the edge (unsigned URLs). These are the
  * 1× base ladder values; DPR ×2/×3 multiples are applied + whitelisted server-side. Import
  * this instead of hardcoding magic widths so an unsupported size is caught in review/IDE.
@@ -77,9 +76,9 @@ export type TransformOptions = {
   height?: number;
   /** Resize fit mode. Default `cover` server-side. */
   fit?: TransformFit;
-  /** Crop gravity. `auto` uses sharp's `attention` strategy. */
+  /** Crop gravity. `auto` picks the region with the most visual salience. */
   gravity?: TransformGravity;
-  /** Output format. `auto` → policy decides (see asset-manager bench). */
+  /** Output format. `auto` → the platform's policy decides. */
   format?: TransformFormat;
   /** Output quality. `auto` → format-specific default. */
   quality?: "auto" | number;
@@ -90,16 +89,15 @@ export type TransformOptions = {
    *
    *   - `removebg`: remove the background; output is a transparent PNG
    *     of the foreground subject. Forces `format=png` regardless of
-   *     other format hints. Runs U²-Net ONNX locally (or BRIA via
-   *     Replicate when `BG_REMOVAL_BACKEND=replicate`). Single cache
-   *     miss per (sha, dsl) tuple; subsequent identical DSLs serve
-   *     from R2 — no inference, no per-image cost.
+   *     other format hints. A single cache miss per (sha, dsl) tuple;
+   *     subsequent identical DSLs serve from cache — no inference, no
+   *     per-image cost.
    *
-   *   - `genfill`: aspect-extension outpaint via Flux-Fill Pro on
-   *     Replicate. Requires BOTH `width` and `height` — the server
+   *   - `genfill`: aspect-extension outpaint. Requires BOTH `width`
+   *     and `height` — the server
    *     fits the source centered into the target canvas and outpaints
    *     the gutters. Output is PNG (forced) at exactly target dims.
-   *     ~$0.05/image first time; same R2 cache as removebg after.
+   *     ~$0.05/image first time; same cache as removebg after.
    *     Primary use case: building OG cards (1200×630) from portrait
    *     listing photos without awkward edge mirroring.
    */
@@ -121,7 +119,7 @@ export type TransformOptions = {
  * the escape hatch for SIGNED URLs that need an off-ladder custom width.
  *
  * The edge whitelist only rejects off-ladder widths on UNSIGNED URLs; a valid
- * `?sig=` earns the whitelist bypass at the worker (the asset-manager still
+ * `?sig=` earns the whitelist bypass at the edge (the server still
  * does the real HMAC check). So a custom width is ONLY safe when the URL is
  * signed — hence this type is accepted exclusively by the signing helpers
  * ({@link getSignedTransformUrl} / `aq.transform(asset, opts, { sign: true })`),
@@ -181,10 +179,10 @@ export function serializeTransform(opts: SignedTransformOptions): string {
 function extForOptions(opts: SignedTransformOptions): string {
   // effect=removebg forces PNG output server-side (needs alpha).
   if (opts.effect === "removebg") return "png";
-  // effect=genfill defaults to WebP (12× lighter than the raw Flux-Fill
+  // effect=genfill defaults to WebP (12× lighter than the raw generated
   // PNG output with no visible loss at q=85). Explicit `format=png`
   // opts back into lossless for print / marketing fold-outs. The server
-  // re-encodes Flux's PNG → target format before R2 cache.
+  // re-encodes the generated PNG → target format before caching.
   if (opts.effect === "genfill") {
     switch (opts.format) {
       case "png":
@@ -222,8 +220,8 @@ function extForOptions(opts: SignedTransformOptions): string {
  * Build a transform URL for a VIDEO asset. Same DSL shape as image
  * transforms; the server branches on the asset's `kind` column. Video
  * URLs use `.mp4` (default) or `.webm` extension and on cache miss the
- * server returns 202 Accepted while a Cloud Run Job encodes the clip;
- * subsequent GETs return 302 to the cached R2 object.
+ * server returns 202 Accepted while a background job encodes the clip;
+ * subsequent GETs return 302 to the cached object.
  *
  *   <video src={aq.transformVideo(asset, { width: 1080, height: 1920 })}
  *          autoPlay muted loop playsInline />
@@ -264,15 +262,30 @@ 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);
  * }
  * ```
  *
- * On first request the server returns 202 Accepted while a Cloud Run
- * Job transcodes the ladder (typically 1-3 min for a 90 s source);
+ * ⚠️ **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
  * progressive MP4 as a fallback source for that window.
  *