@nitida/asset-client 0.16.1 → 0.16.3

package/dist/index.d.cts

@@ -51,14 +51,14 @@ declare function getTextColorForBackground(swatch: PaletteSwatch | string | null
 /** Luminancia relativa WCAG de un hex. 0 = negro, 1 = blanco. */
 declare 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.
  */
 declare function contrastRatio(l1: number, l2: number): number;
 /**
- * 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.
  */
 declare function bestTextContrast(hex: string): {
     color: "#000000" | "#FFFFFF";
@@ -98,9 +98,9 @@ declare function getPaletteBlurBackground(palette: AssetPalette | null | undefin
  * 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,
@@ -137,8 +137,8 @@ type SlotResolution = {
  *
  *   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",
  *   });
  */
 declare function configureSlotResolver(opts: {
@@ -173,10 +173,9 @@ declare function resolveSlots(slotKeys: string[], opts?: ResolveSlotOptions): Pr
  * 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
@@ -191,7 +190,7 @@ declare function resolveSlots(slotKeys: string[], opts?: ResolveSlotOptions): Pr
  */
 
 /**
- * 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.
@@ -221,9 +220,9 @@ 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;
@@ -234,16 +233,15 @@ 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.
      */
@@ -264,7 +262,7 @@ 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 })`),
@@ -305,8 +303,8 @@ declare function serializeTransform(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 />
@@ -338,15 +336,30 @@ declare function getVideoTransformUrl(asset: Pick<AssetDTO, "sha">, opts: Transf
  * 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.
  *
@@ -418,8 +431,8 @@ declare function getTransformSrcSet(asset: Pick<AssetDTO, "sha">, widths: number
  * USED for, removing the implicit landscape-only assumption that bit us
  * with vertical product photos.
  */
-type VariantPreset = "thumb" | "sm" | "md" | "lg" | "xl" | "original" | "poster" | "video" | "aiproxy" | "mp3";
-/** 1-char alias used in R2 keys / wire `presets` string. */
+type VariantPreset = "thumb" | "sm" | "md" | "lg" | "xl" | "original" | "poster" | "video" | "aiproxy" | "hls" | "mp3";
+/** 1-char alias used in storage keys / wire `presets` string. */
 declare const PRESET_SHORT: Record<VariantPreset, string>;
 declare const PRESET_LONG: Record<string, VariantPreset>;
 /** Variant extension by preset. Image variants are always WebP, video MP4. */
@@ -435,11 +448,11 @@ 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
@@ -453,9 +466,79 @@ type AssetVariant = {
      *
      * Absent on variants written before the trace field existed.
      */
-    sourceFrom?: VariantPreset | "upload";
+    sourceFrom?: VariantPreset | "upload" | "transform-route" | "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.
+ */
+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).
+ */
+declare function getHlsLadder(asset: Pick<AssetDTO, "variants">): AssetVariant | 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.
+ */
+declare function hlsLadderAlignment(rungs: HlsRung[]): {
+    rungCount: number;
+    ceilingHeight: number;
+    floorHeight: number;
+    switchable: boolean;
+    aligned: boolean | null;
+    minSegments: number | null;
 };
 /**
  * Compact wire shape — what the server actually sends. Aliases (`w`, `h`,
@@ -559,7 +642,7 @@ declare function getAssetUrl(asset: Pick<AssetDTO, "sha"> & OriginalHints, prese
  * 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
@@ -588,4 +671,4 @@ declare function getAssetDimensions(asset: Pick<AssetDTO, "w" | "h">): {
     height: number;
 } | null;
 
-export { type AssetDTO, type AssetPalette, type AssetVariant, PRESET_EXT, PRESET_LONG, PRESET_MAX_DIM, PRESET_SHORT, type PaletteSwatch, type ResolveSlotOptions, type SignedTransformOptions, type SlotDTO, type SlotResolution, TRANSFORM_WIDTHS, type TransformEffect, type TransformFit, type TransformFormat, type TransformGravity, type TransformOptions, type TransformWidth, type VariantPreset, bestTextContrast, computeVariantDimensions, configureSlotResolver, contrastRatio, extractAssetSha, getAmbientGradient, getAssetDimensions, getAssetSrcSet, getAssetUrl, getCdnBase, getHlsStreamingUrl, getPaletteBlurBackground, getPaletteCssVars, getSignedTransformUrl, getTenantId, getTextColorForBackground, getTransformSrcSet, getTransformUrl, getVideoTransformUrl, hasPreset, invalidateSlotCache, iteratePaletteSwatches, pickAmbientBackground, relativeLuminance, resolveSlot, resolveSlots, serializeTransform, setCdnBase, setTenantId, signTransformUrl };
+export { type AssetDTO, type AssetPalette, type AssetVariant, type HlsRung, PRESET_EXT, PRESET_LONG, PRESET_MAX_DIM, PRESET_SHORT, type PaletteSwatch, type ResolveSlotOptions, type SignedTransformOptions, type SlotDTO, type SlotResolution, TRANSFORM_WIDTHS, type TransformEffect, type TransformFit, type TransformFormat, type TransformGravity, type TransformOptions, type TransformWidth, type VariantPreset, bestTextContrast, computeVariantDimensions, configureSlotResolver, contrastRatio, extractAssetSha, getAmbientGradient, getAssetDimensions, getAssetSrcSet, getAssetUrl, getCdnBase, getHlsLadder, getHlsStreamingUrl, getPaletteBlurBackground, getPaletteCssVars, getSignedTransformUrl, getTenantId, getTextColorForBackground, getTransformSrcSet, getTransformUrl, getVideoTransformUrl, hasPreset, hlsLadderAlignment, invalidateSlotCache, iteratePaletteSwatches, pickAmbientBackground, relativeLuminance, resolveSlot, resolveSlots, serializeTransform, setCdnBase, setTenantId, signTransformUrl };

package/dist/index.d.ts

@@ -51,14 +51,14 @@ declare function getTextColorForBackground(swatch: PaletteSwatch | string | null
 /** Luminancia relativa WCAG de un hex. 0 = negro, 1 = blanco. */
 declare 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.
  */
 declare function contrastRatio(l1: number, l2: number): number;
 /**
- * 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.
  */
 declare function bestTextContrast(hex: string): {
     color: "#000000" | "#FFFFFF";
@@ -98,9 +98,9 @@ declare function getPaletteBlurBackground(palette: AssetPalette | null | undefin
  * 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,
@@ -137,8 +137,8 @@ type SlotResolution = {
  *
  *   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",
  *   });
  */
 declare function configureSlotResolver(opts: {
@@ -173,10 +173,9 @@ declare function resolveSlots(slotKeys: string[], opts?: ResolveSlotOptions): Pr
  * 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
@@ -191,7 +190,7 @@ declare function resolveSlots(slotKeys: string[], opts?: ResolveSlotOptions): Pr
  */
 
 /**
- * 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.
@@ -221,9 +220,9 @@ 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;
@@ -234,16 +233,15 @@ 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.
      */
@@ -264,7 +262,7 @@ 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 })`),
@@ -305,8 +303,8 @@ declare function serializeTransform(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 />
@@ -338,15 +336,30 @@ declare function getVideoTransformUrl(asset: Pick<AssetDTO, "sha">, opts: Transf
  * 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.
  *
@@ -418,8 +431,8 @@ declare function getTransformSrcSet(asset: Pick<AssetDTO, "sha">, widths: number
  * USED for, removing the implicit landscape-only assumption that bit us
  * with vertical product photos.
  */
-type VariantPreset = "thumb" | "sm" | "md" | "lg" | "xl" | "original" | "poster" | "video" | "aiproxy" | "mp3";
-/** 1-char alias used in R2 keys / wire `presets` string. */
+type VariantPreset = "thumb" | "sm" | "md" | "lg" | "xl" | "original" | "poster" | "video" | "aiproxy" | "hls" | "mp3";
+/** 1-char alias used in storage keys / wire `presets` string. */
 declare const PRESET_SHORT: Record<VariantPreset, string>;
 declare const PRESET_LONG: Record<string, VariantPreset>;
 /** Variant extension by preset. Image variants are always WebP, video MP4. */
@@ -435,11 +448,11 @@ 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
@@ -453,9 +466,79 @@ type AssetVariant = {
      *
      * Absent on variants written before the trace field existed.
      */
-    sourceFrom?: VariantPreset | "upload";
+    sourceFrom?: VariantPreset | "upload" | "transform-route" | "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.
+ */
+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).
+ */
+declare function getHlsLadder(asset: Pick<AssetDTO, "variants">): AssetVariant | 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.
+ */
+declare function hlsLadderAlignment(rungs: HlsRung[]): {
+    rungCount: number;
+    ceilingHeight: number;
+    floorHeight: number;
+    switchable: boolean;
+    aligned: boolean | null;
+    minSegments: number | null;
 };
 /**
  * Compact wire shape — what the server actually sends. Aliases (`w`, `h`,
@@ -559,7 +642,7 @@ declare function getAssetUrl(asset: Pick<AssetDTO, "sha"> & OriginalHints, prese
  * 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
@@ -588,4 +671,4 @@ declare function getAssetDimensions(asset: Pick<AssetDTO, "w" | "h">): {
     height: number;
 } | null;
 
-export { type AssetDTO, type AssetPalette, type AssetVariant, PRESET_EXT, PRESET_LONG, PRESET_MAX_DIM, PRESET_SHORT, type PaletteSwatch, type ResolveSlotOptions, type SignedTransformOptions, type SlotDTO, type SlotResolution, TRANSFORM_WIDTHS, type TransformEffect, type TransformFit, type TransformFormat, type TransformGravity, type TransformOptions, type TransformWidth, type VariantPreset, bestTextContrast, computeVariantDimensions, configureSlotResolver, contrastRatio, extractAssetSha, getAmbientGradient, getAssetDimensions, getAssetSrcSet, getAssetUrl, getCdnBase, getHlsStreamingUrl, getPaletteBlurBackground, getPaletteCssVars, getSignedTransformUrl, getTenantId, getTextColorForBackground, getTransformSrcSet, getTransformUrl, getVideoTransformUrl, hasPreset, invalidateSlotCache, iteratePaletteSwatches, pickAmbientBackground, relativeLuminance, resolveSlot, resolveSlots, serializeTransform, setCdnBase, setTenantId, signTransformUrl };
+export { type AssetDTO, type AssetPalette, type AssetVariant, type HlsRung, PRESET_EXT, PRESET_LONG, PRESET_MAX_DIM, PRESET_SHORT, type PaletteSwatch, type ResolveSlotOptions, type SignedTransformOptions, type SlotDTO, type SlotResolution, TRANSFORM_WIDTHS, type TransformEffect, type TransformFit, type TransformFormat, type TransformGravity, type TransformOptions, type TransformWidth, type VariantPreset, bestTextContrast, computeVariantDimensions, configureSlotResolver, contrastRatio, extractAssetSha, getAmbientGradient, getAssetDimensions, getAssetSrcSet, getAssetUrl, getCdnBase, getHlsLadder, getHlsStreamingUrl, getPaletteBlurBackground, getPaletteCssVars, getSignedTransformUrl, getTenantId, getTextColorForBackground, getTransformSrcSet, getTransformUrl, getVideoTransformUrl, hasPreset, hlsLadderAlignment, invalidateSlotCache, iteratePaletteSwatches, pickAmbientBackground, relativeLuminance, resolveSlot, resolveSlots, serializeTransform, setCdnBase, setTenantId, signTransformUrl };