@nitida/asset-client 0.16.2 → 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: {
@@ -336,13 +336,28 @@ 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);
  * }
  * ```
  *
+ * ⚠️ **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
@@ -416,7 +431,7 @@ 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";
+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>;
@@ -451,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`,
@@ -557,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
@@ -586,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: {
@@ -336,13 +336,28 @@ 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);
  * }
  * ```
  *
+ * ⚠️ **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
@@ -416,7 +431,7 @@ 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";
+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>;
@@ -451,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`,
@@ -557,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
@@ -586,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.js

@@ -336,6 +336,11 @@ var PRESET_SHORT = {
   poster: "p",
   video: "v",
   aiproxy: "a",
+  // `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
@@ -356,6 +361,9 @@ var PRESET_EXT = {
   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"
 };
 var PRESET_MAX_DIM = {
@@ -368,10 +376,30 @@ var PRESET_MAX_DIM = {
   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
 };
+function getHlsLadder(asset) {
+  return asset.variants?.find((v) => v.preset === "hls") ?? null;
+}
+function hlsLadderAlignment(rungs) {
+  const heights = rungs.map((r) => r.height);
+  const measured = rungs.map((r) => r.segments).filter((s) => 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
+  };
+}
 var cdnBaseUrl = "https://8ok.uk";
 function setCdnBase(url) {
   cdnBaseUrl = url.replace(/\/$/, "");
@@ -404,15 +432,13 @@ var ORIGINAL_EXT_BY_MIME = {
   "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",
@@ -431,6 +457,11 @@ function getAssetUrl(asset, preset) {
     const ext = asset.oext || originalExtForMime(asset.mime);
     return `${cdnBaseUrl}/${variantPrefix()}${asset.sha}-${PRESET_SHORT.original}.${ext}`;
   }
+  if (preset === "hls") {
+    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]}`;
 }
 function hasPreset(asset, preset) {
@@ -477,6 +508,7 @@ export {
   getAssetSrcSet,
   getAssetUrl,
   getCdnBase,
+  getHlsLadder,
   getHlsStreamingUrl,
   getPaletteBlurBackground,
   getPaletteCssVars,
@@ -487,6 +519,7 @@ export {
   getTransformUrl,
   getVideoTransformUrl,
   hasPreset,
+  hlsLadderAlignment,
   invalidateSlotCache,
   iteratePaletteSwatches,
   pickAmbientBackground,