@nitida/sdk 0.25.3 → 0.27.0

package/skills/nitida-sdk/SKILL.md

@@ -87,7 +87,7 @@ const COVER_CROP = { fit: "cover", gravity: "auto" } as const;
 
 Output URL shape: `https://8ok.uk/t/format=webp,width=640/<sha16>.webp`.
 
-⚠️ **Widths MUST be on the unsigned ladder** `TRANSFORM_WIDTHS` (`160,240,256,320,400,480,600,640,800,960,1080,1200,1280,1440,1600,1920,2560,3840`). Any other width → **HTTP 400** at the edge (DoS guard). The `TransformWidth` type makes an off-ladder width a compile error — import the type, don't hardcode magic numbers. (For a one-off custom width you'd need signed URLs; not used here.)
+⚠️ **Widths MUST be on the unsigned ladder** `TRANSFORM_WIDTHS` (`96,128,160,240,256,320,400,480,600,640,800,960,1080,1200,1280,1440,1600,1920,2560,3840` — 20 widths). Any other width → **HTTP 400** at the edge (DoS guard). The `TransformWidth` type makes an off-ladder width a compile error — import the type, don't hardcode magic numbers. (For a one-off custom width you'd need signed URLs; not used here.)
 
 ## 2b. A responsive gallery — the widths, with their measured weight
 
@@ -153,9 +153,11 @@ everyone, and the ladder buys you nothing.
   platform does not use it.
 - Grid cells: `{ fit: "cover", gravity: "auto" }` — verified to return an exact
   400×400. Lightbox: `fit: "inside"`, never crops.
-- ⚠️ **There is no upscale — the master is the ceiling.** Measured: a 2400 px
+- ⚠️ **`/t/` never upscales — the master is the ceiling.** Measured: a 2400 px
   master asked for `width=2560` returns **2400 px**. Put widths in the `srcSet`
   that your sources can sustain.
+  (There IS a paid, separate `POST /assets/:id/upscale` that genuinely enlarges
+  with a model. It is not the transform route and it is not free — §8g.)
 - ⚠️ The **first** request of each width is generated cold, then cached at the
   edge immutably. Warm them after upload if the first visitor matters.
 
@@ -219,7 +221,7 @@ export function videoUrl(sha: string, tenantId = TENANT_ID): string {
 Output: `https://8ok.uk/<tenantId.toString(36)>/v/<sha16>-v.mp4`.
 
 **Do NOT:**
-- ❌ Use `getVideoTransformUrl` — that builds a `/t/...` transform URL, which **410s** for a stored video sha. (`getVideoTransformUrl` is for on-the-fly re-encodes, a different feature.)
+- ❌ Use `getVideoTransformUrl` — that builds a `/t/...` transform URL, which never returns playable video. On a video sha `/t/` transforms the **poster frame**: `200 image/webp` with `x-transform-source: poster` when a poster exists, `410` when it does not. (`getVideoTransformUrl` is for on-the-fly re-encodes, a different feature.)
 - ❌ Hand-roll the path with the decimal tenant id. The path segment is **base36**: `tenantId.toString(36)`. **Tenant 10 → `/a/v/`**, and the decimal `/10/v/` **404s**. This is invisible for tenants ≤ 9 (`8`→`8`, `9`→`9`) and bit a real migration only at tenant 10. Always delegate to `getAssetUrl` so the encoding can't drift.
 
 **Audio IS supported (updated 2026-07-01 — verify against the SDK types, this used to say "not supported").** The platform recognizes `kind: "image" | "video" | "document" | "audio" | "other"` and ships an **`mp3`** variant preset (`VariantPreset` in `@nitida/asset-client`). Uploads are hash-deduped (byte-identical re-uploads return the existing sha — that's *byte* dedup, NOT semantic "find a similar track"). `nt.upload` also accepts an `audioTrack` on video-composition calls. Serve via the `mp3` preset / `original`. Confirm the current preset/kind list in `node_modules/@nitida/asset-client/dist/index.d.ts` before relying on a specific ext.
@@ -382,7 +384,11 @@ hls.js, which cannot start there, and fall through to the MP4. The `|| !MediaSou
 covers it: native if the engine is Apple's **OR** if there is no MSE to fall back on.
 
 **When you use hls.js, stop it guessing** — the defaults are how a fast connection still opens at
-240p: `{ startLevel: -1, testBandwidth: true, abrEwmaDefaultEstimate: 1_000_000 }`.
+240p. ⚠️ **Do NOT pass `startLevel: -1` together with `testBandwidth: true`** — measured,
+that pair is the *cause*: on a clip short enough to be one segment the bandwidth probe IS
+the whole video, so it plays at the bottom rung start to finish (a 5.04 s 4K asset was
+delivered at 426×240 because of it). Leave the start level unset and raise the estimate:
+`{ abrEwmaDefaultEstimate: 5_000_000 }`.
 
 **The first request can answer `202`** while the background job builds the ladder (1–3 min for a
 90 s source), then `302`s to the cached master. Keep the progressive MP4 as the fallback `<source>`
@@ -396,7 +402,7 @@ What it does NOT do is prefer Apple's engine where both work: a modern iPhone ge
 hls.js tuning goes in the `config` prop:
 
 ```tsx
-const HLS_CONFIG = { capLevelToPlayerSize: false, startLevel: -1, testBandwidth: true, abrEwmaDefaultEstimate: 1_000_000 };
+const HLS_CONFIG = { capLevelToPlayerSize: false, abrEwmaDefaultEstimate: 5_000_000 };
 <HlsVideo src={getHlsStreamingUrl(asset)} config={HLS_CONFIG} poster={poster} playsInline crossOrigin="anonymous" />
 ```
 
@@ -473,6 +479,68 @@ That replaces the older hand-run provisioning scripts and SQL that used to live
 
 Variant preset short codes: `thumb=q, sm=s, md=m, lg=l, xl=x, original=o, poster=p, video=v`. Exts: images `webp`, video `mp4`.
 
+
+## Private assets — `visibility`
+
+Default is `"public"`. Set `private` and **every public door answers 404** —
+stored variants, the raw original, the HLS ladder, and `/t/` (including the
+poster frame of a private video). The bytes come back only through a signed URL
+that expires.
+
+```ts
+import { getPrivateAssetUrl, getPrivateTransformUrl } from "@nitida/sdk";
+// ON YOUR BACKEND, once you decided this viewer may see it:
+await getPrivateAssetUrl(asset, "lg", signingKey, { expiresInSeconds: 300 });
+await getPrivateTransformUrl(asset, { width: 1280 }, signingKey, { expiresInSeconds: 300 });
+```
+
+- **A 404 on a private asset is NOT a missing file.** Check `visibility` on the
+  DTO before you check storage. It is the number-one support question.
+- **Seven URL builders throw** rather than hand you a doomed URL — `getAssetUrl`,
+  `getAssetSrcSet`, `getTransformUrl`, `getTransformSrcSet`,
+  `getVideoTransformUrl`, `getHlsStreamingUrl`, `getSignedTransformUrl` — but
+  only when the value you pass carries `visibility`. `{ sha }` alone is never
+  refused.
+- **`exp` is mandatory**; revocation is *"within a minute"* (60 s TTL at the edge).
+- **The signing key is a backend secret** — it mints URLs for every private
+  asset the tenant owns.
+
+## Two ways an image gets smaller, and only one of them is yours to call
+
+This is the question every programmatic caller gets wrong, so it is stated flat:
+
+| | who does it | what it shrinks |
+|---|---|---|
+| **Client compressor** (browser / Expo) | the UI, before the PUT | the **upload**: quality 0.85, max 2880 px, WebP. iPhone 9.1 MB → 1.8 MB |
+| **Variants + `/t/`** | the backend, on request | the **delivery**: 19 MB JPEG → 170 kB WebP at 1920 |
+
+**The backend never recompresses the raw. Ever.** That is deliberate: the raw
+has to stay pristine so variants are *regenerable* — the day you add AVIF or
+raise the max dimension, the pipeline re-runs against it. A client→server lossy
+chain bakes artifacts in forever.
+
+So for an API/agent upload there is nothing to "turn on": you were never going
+to compress the raw, and delivery is already optimised two ways.
+
+```ts
+// Ask for the rungs you will actually render…
+await aq.upload(file, { presets: ["original", "thumb", "md", "lg"] });
+
+// …or upload bare and let the transform route make them on demand:
+aq.transform(asset, { width: 1280, format: "webp" });   // → /t/…, cached after the first hit
+```
+
+**`presets` defaults to `["original"]`** — a bare upload stores the raw and no
+rendition. Since 2026-08-22 that is no longer a trap: when the DTO says a preset
+was never materialised, `getAssetUrl` / `urlFor` **fall back to `/t/`** instead
+of returning a URL that 404s. You still get optimised bytes; you just pay the
+first encode. Prefer naming the presets when you know what you will render.
+
+⚠️ `getAssetSrcSet` deliberately does **not** fall back — a srcSet promises
+pixel widths and a transform cannot keep that promise on a source smaller than
+the rung, because the pipeline never enlarges. An empty srcSet degrades to `src`; a lying one
+degrades to a wrong choice.
+
 ## 7. Browser-direct uploads — three things that only fail in a real browser
 
 Measured 2026-08-15 on the public bench at <https://media-harness.vercel.app> — no credentials
@@ -505,7 +573,7 @@ needed. Reproduce there before debugging any of these by hand.
 | Symptom | Cause |
 |---|---|
 | **400** on an image URL | width not on `TRANSFORM_WIDTHS` ladder |
-| **410** on a video URL | used `/t/` (transform) for a stored video — use `getAssetUrl(...,'video')` |
+| **410** on a video `/t/` URL | that video has no `poster`. With one, `/t/` returns the poster as an image, never the video — use `getAssetUrl(...,'video')` |
 | **404** on a video URL | decimal tenant prefix (`/10/v/`) instead of base36 (`/a/v/`) — call `setTenantId` + `getAssetUrl`. Tenant 12 → `/c/v/` |
 | `process returned no assetId` | fixed in the 2026-08-16 deploy — you are on a server deploy older than that, §7.2 |
 | `waitReady timeout` on a video | a transcode + HLS ladder takes 1–2 min; the default `timeoutMs` is 5 min but a 4K source can beat it. Raise it, §7.2 |
@@ -601,9 +669,34 @@ job. Skip `aiproxy` when nothing reads it — it is an extra encode per video.
   `TransformOptions.width` is the ladder union; `SignedTransformOptions.width`
   is `number`. Unsigned off-ladder = 400 at the edge (DoS guard). Sign
   server-side.
-- **Upscale** → `POST /assets/:id/upscale`, idempotent on
-  `(tenant, sha, preset, provider)`, async, with `/poll` as the missed-webhook
-  fallback.
+- **Upscale** → `POST /assets/:id/upscale`. **A paid add-on, and the SDK does
+  not expose it on purpose** — €0.10 a metered run, so it is never something a
+  helper should make easy to call in a loop. Call it over HTTP, deliberately.
+
+  ```jsonc
+  // POST /assets/:id/upscale     Authorization: Bearer amk_mt_…
+  {
+    "mode": "target" | "factor" | "enhance",   // REQUIRED
+    "targetMp":  1..128,        // mode=target — megapixels to reach
+    "factor":    1..8,          // mode=factor — multiplier
+    "outputFormat":  "jpg" | "png" | "webp",
+    "outputQuality": 0..100,
+    "enhanceDetails": true,     // mode=enhance
+    "enhanceRealism": true,     // mode=enhance
+    "provider": "wavespeed-phota-enhance"        // €0.09
+              | "replicate-p-image-upscale"      // €0.01
+              | "wavespeed-clarity-flux-upscaler"
+  }
+  ```
+
+  `mode` is the only required field; `enhance` ignores `targetMp` and `factor`.
+  Idempotent on `(tenant, sha, preset, provider)`, async, with `/poll` as the
+  missed-webhook fallback.
+
+  ⚠️ **It needs an `amk_mt_*` key, not your runtime key.** Since 2026-08-21 a
+  runtime key carries no metered op and is refused with zero allowance — the
+  credential that can spend money is issued separately, rate-limited 60/min, and
+  revocable on its own. Ask for one; it is not part of the default triplet.
 - **Usage** → `nt.usage.snapshot() | timeseries(days) | keys()`. Wire `keys()`
   early: per-key attribution is the cheap answer to "what caused this spike".
 

package/src/audio-compat.ts

@@ -0,0 +1,37 @@
+/**
+ * Which audio uploads already play everywhere — the single source of truth for
+ * both the server's transcode guard and the client's delivery-preset choice.
+ *
+ * It lives in its own module, rather than beside the preset order that uses it,
+ * for a mechanical reason: `apps/asset-manager` imports it by relative path.
+ * The SDK is a PUBLISHED package, so its `exports` point at `dist/`, and
+ * `dist/` is gitignored — it does not exist inside the Docker image, which
+ * copies `packages/` as source. A bare `@nitida/sdk` import type-checks on any
+ * machine that built the package once and then fails the image build. (It did,
+ * on 2026-08-22, with `@nitida/asset-client`.) A single small file keeps that
+ * relative import from dragging the whole client into the server.
+ *
+ * Two copies of this list drifting apart is how a platform ends up generating
+ * a variant its own client refuses to use — which is exactly the bug this
+ * predicate was introduced to end.
+ */
+
+/**
+ * `true` when a browser can play these bytes as uploaded, so re-encoding them
+ * to MP3 buys nothing.
+ *
+ * - `audio/mpeg` — unambiguous.
+ * - `audio/mp4` / `audio/aac` — plays in Safari, Chrome, Firefox and Edge on
+ *   desktop and mobile. The historical worry was old AOSP builds without
+ *   proprietary codecs; the call to treat AAC as universal was made with the
+ *   platform's one real AAC consumer, whose viewer is WebGL — a device that
+ *   cannot decode AAC cannot run that product at all, so the fallback would
+ *   only ever protect a device that had already lost.
+ *
+ * Deliberately NOT here: `audio/webm` and `audio/ogg` (Opus). iOS Safari
+ * cannot decode them, and that is the case the MP3 fallback exists for.
+ */
+export function isUniversallyPlayableAudio(mime: string): boolean {
+  const base = (mime.split(";")[0] ?? "").trim().toLowerCase();
+  return base === "audio/mpeg" || base === "audio/mp4" || base === "audio/aac";
+}

package/src/expo/index.ts

@@ -26,6 +26,33 @@
  *   const { assetId } = await upload.start();
  *   await aq.slots.bind("storefront.tour.video", { assetId, preset: "video" });
  *
+ * ⚠️ THIS PATH PUTS A RUNTIME KEY ON THE DEVICE. Read before shipping.
+ *
+ * `createExpoUploader` reads `client.opts.apiKey` and hands it to the native
+ * session as its `authToken` (see below — it is four lines, and they are the
+ * whole story). The native uploader talks to the API directly, so it needs a
+ * credential the OS can replay hours later from a background task. There is no
+ * BFF in that loop to inject one.
+ *
+ * That is the opposite of what every other surface here does, and the opposite
+ * of what `@nitida/sdk/web` chose when it hit the SAME constraint: `/web`
+ * deliberately does NOT expose the multipart uploader, because it needs a raw
+ * `authToken` a BFF cannot supply. `/expo` exposes it anyway, because
+ * background-surviving uploads are the entire reason a native session exists.
+ *
+ * So, concretely, an `amk_rt_*` key in your app bundle is readable by anyone
+ * who unzips the IPA/APK, and it is a WRITE key to a paid platform.
+ *
+ *   - Uploading big video in the background is worth it to you ⇒ use this, and
+ *     scope the key to one tenant so a leak is contained and revocable.
+ *   - It is not ⇒ build the client from `@nitida/sdk/web` pointed at your own
+ *     route and call `aq.upload(file)`. No key on the device. You lose survival
+ *     across backgrounding and OS kill; the upload dies with the JS thread.
+ *
+ * The real fix — a BFF-minted short-lived token the native session can carry —
+ * is not built. It is the same gap `/web` documents. Ask; there is no public
+ * tracker.
+ *
  * Peer dep: `@aquienpz/asset-uploader-expo` (lazy — apps that don't
  * use the mobile SDK skip the install).
  * @module @nitida/sdk/expo
@@ -44,9 +71,11 @@ export type ExpoUploadOptions = Omit<
 
 /**
  * Spawn a native-backed `UploadTask` bound to a configured client.
- * Inherits the client's endpoint / api key / tenant scope; caller only
- * has to supply the file input + any per-upload tuning (partSize,
- * concurrency).
+ *
+ * ⚠️ It reaches into the client for `apiKey` and uses it as the session's
+ * `authToken`, so the client you pass MUST have been built with a real runtime
+ * key — which means that key is on the device. See the module header for what
+ * that costs and what the alternative is.
  */
 export function createExpoUploader(
   client: NitidaClient,

package/src/index.ts

@@ -48,6 +48,7 @@ import {
   getVideoTransformUrl,
   hasPreset,
   invalidateSlotCache,
+  type RequestablePreset,
   type ResolveSlotOptions,
   resolveSlot,
   resolveSlots,
@@ -57,8 +58,10 @@ import {
   setCdnBase,
   setTenantId,
   type TransformOptions,
+  type VariantEntryPreset,
   type VariantPreset,
 } from "@nitida/asset-client";
+import { isUniversallyPlayableAudio } from "./audio-compat";
 
 // ---------------------------------------------------------------------------
 // Config
@@ -112,7 +115,9 @@ export type NitidaClientOptions = {
    * only when calling `aq.transform(asset, opts, { sign: true })`.
    *
    * 32 random bytes, generated server-side on tenant creation; fetch
-   * via `GET /admin/tenants/:id` with an admin key. **Keep it
+   * via `POST /admin/projects/:code/rotate-signing-key`, which needs a
+   * SYSTEM-scope credential the platform operator holds — your own admin key
+   * answers `403 SYSTEM_KEY_REQUIRED`. Ask for it. **Keep it
    * server-side only** — do not ship in `NEXT_PUBLIC_*` env vars. Sign
    * URLs from a BFF route handler, or pre-sign at build time.
    */
@@ -203,7 +208,9 @@ export type {
   AssetVariant,
   HlsRung,
   PaletteSwatch,
+  RequestablePreset,
   ResolveSlotOptions,
+  SignAccessOptions,
   SignedTransformOptions,
   SlotDTO,
   SlotResolution,
@@ -213,13 +220,18 @@ export type {
   TransformGravity,
   TransformOptions,
   TransformWidth,
+  VariantEntryPreset,
   VariantPreset,
+  VisibilityHint,
 } from "@nitida/asset-client";
 export {
+  accessMessage,
+  assertPublic,
   bestTextContrast,
   computeVariantDimensions,
   configureSlotResolver,
   contrastRatio,
+  deriveAccessKey,
   extractAssetSha,
   getAmbientGradient,
   getAssetDimensions,
@@ -230,6 +242,8 @@ export {
   getHlsStreamingUrl,
   getPaletteBlurBackground,
   getPaletteCssVars,
+  getPrivateAssetUrl,
+  getPrivateTransformUrl,
   getSignedTransformUrl,
   getTenantId,
   getTextColorForBackground,
@@ -251,6 +265,7 @@ export {
   serializeTransform,
   setCdnBase,
   setTenantId,
+  signAccessUrl,
   signTransformUrl,
   TRANSFORM_WIDTHS,
 } from "@nitida/asset-client";
@@ -464,8 +479,11 @@ export type PresignUploadUrlOptions = {
   /**
    * Variant ladder to generate after `/assets/process`. Defaults to
    * `["original"]` server-side when omitted — same contract as `aq.upload`.
+   *
+   * {@link RequestablePreset}, not {@link VariantPreset}: `hls` and `mp3` are
+   * things a variant can BE, never things you can ask for, and asking is a 400.
    */
-  presets?: VariantPreset[];
+  presets?: RequestablePreset[];
   /**
    * Pre-compression size of the source (useful when the browser ran
    * compressorjs / heic2any before computing `bytes`). Recorded
@@ -618,9 +636,10 @@ class AssetsApi {
   }
 
   /**
-   * Add or rebuild variants on an existing asset. Image presets are
-   * MERGED with what's there — passing `{ presets: ["thumb"] }` adds
-   * the thumb variant without touching `lg`, `sm`, `original`, etc.
+   * Add or rebuild variants on an existing asset. Presets are MERGED
+   * with what's there, for images AND for video — passing
+   * `{ presets: ["thumb"] }` adds the thumb variant without touching
+   * `lg`, `sm`, `original`, etc.
    *
    *   // Day 0: upload original-only logo
    *   const { assetId } = await aq.upload(logoFile);  // defaults to ["original"]
@@ -639,14 +658,22 @@ class AssetsApi {
    * reading the source bytes from the permanent `original` variant —
    * no need to re-upload.
    *
-   * Video presets are filtered to `["poster","video","aiproxy"]` and
-   * dispatched to a background job (the call returns immediately
+   * Video presets are filtered to `["poster","video","aiproxy","probe"]`
+   * and dispatched to a background job (the call returns immediately
    * with a dispatch handle; poll `aq.assets.get(id).status` for
    * completion).
+   *
+   * ⚠️ Before 2026-08-22 the video path REPLACED the whole variant
+   * registry instead of merging, so a partial regenerate silently
+   * deregistered `poster`, `video` and — irrecoverably — `hls`, which
+   * is not a {@link RequestablePreset} and therefore cannot be asked
+   * for again. The objects kept serving from the CDN; only the
+   * registry died. Fixed server-side; a client on an older server
+   * still loses them.
    */
   async regenerate(
     assetId: string,
-    opts: { presets?: VariantPreset[] } = {},
+    opts: { presets?: RequestablePreset[] } = {},
   ): Promise<RegenerateResult> {
     const r = await fetch(
       endpointHref(this.opts, `/assets/${assetId}/regenerate`),
@@ -945,8 +972,12 @@ export type UploadOptions = {
    * Idempotent: you can always add missing variants later via
    * `aq.assets.regenerate(id, { presets: [...] })`. The platform
    * stores the source so regeneration doesn't require re-uploading.
+   *
+   * {@link RequestablePreset}, not {@link VariantPreset}. `hls` and `mp3` are
+   * produced FOR you — the ladder when a video transcodes, the mp3 alongside
+   * any audio original — and asking for either is a 400.
    */
-  presets?: VariantPreset[];
+  presets?: RequestablePreset[];
   /**
    * Max time to wait for the asset to transition to `ready` (or `failed`)
    * after dispatch. Default `5 * 60_000` (5 min). Bump higher for large
@@ -973,8 +1004,16 @@ export type UploadOptions = {
   video?: UploadVideoOptions;
 };
 
-/** Default preset set the SDK sends to `/assets/upload-url` when the caller omits `presets`. */
-const DEFAULT_UPLOAD_PRESETS: VariantPreset[] = ["original"];
+/**
+ * Default preset set the SDK sends to `/assets/upload-url` when the caller
+ * omits `presets`.
+ *
+ * Typed `RequestablePreset[]`, not `VariantPreset[]` — it is a REQUEST. The
+ * distinction caught this very line the moment it was introduced: it was the
+ * wrong type here, and a `VariantPreset[]` default could have carried `hls`
+ * into a request that answers 400.
+ */
+const DEFAULT_UPLOAD_PRESETS: RequestablePreset[] = ["original"];
 
 export type UploadResult = {
   assetId: string;
@@ -1139,6 +1178,8 @@ class UsageApi {
   }
 }
 
+export { isUniversallyPlayableAudio } from "./audio-compat";
+
 export class NitidaClient {
   readonly slots: SlotsApi;
   readonly assets: AssetsApi;
@@ -1238,7 +1279,7 @@ export class NitidaClient {
     if (!this.opts.signingKey) {
       throw new Error(
         "aq.transform({ sign: true }) requires `signingKey` in NitidaClientOptions. " +
-          "Pull the tenant's signing key from /admin/tenants/:id and pass it to the SDK constructor on a SERVER-side instance only.",
+          "No signingKey on this client. The key is minted by POST /admin/projects/:code/rotate-signing-key, which needs a system-scope credential the platform operator holds — your own admin key gets 403 SYSTEM_KEY_REQUIRED, so ask for it. Then pass it to the SDK constructor on a SERVER-side instance only.",
       );
     }
     // Signed path — custom (off-ladder) widths allowed. Empty opts → no
@@ -1614,15 +1655,35 @@ export class NitidaClient {
    * `presets` string. Falls back through the preference order
    *   lg → md → sm → thumb → original   (for images)
    *   video → poster                    (for videos)
-   *   mp3 → original                    (for audio)
+   *   original → mp3                    (for audio ALREADY playable everywhere)
+   *   mp3 → original                    (for any other audio)
    * so an upload that was processed with e.g. `["original"]` still
    * returns a non-404 URL in `aq.upload`'s result.
+   *
+   * ⭐ Why audio branches on the source mime (changed 2026-08-22).
+   *
+   * It used to be `mp3 → original` unconditionally, so `upload().cdnUrl`
+   * handed back the server's auto-generated mp3 — libmp3lame, mono ~96 kbps —
+   * even when the caller had uploaded an MP3 or an AAC that already plays in
+   * every target browser. A consumer asking for "my file" silently received a
+   * re-encoded, lower-quality one, with no error to notice.
+   *
+   * Measured across the platform: of 126 audio assets carrying an mp3 variant,
+   * **105 had an `audio/mpeg` source** — an MP3 re-encoded into an MP3, for
+   * zero compatibility gain.
+   *
+   * The mp3 still wins for `audio/webm`/Opus and anything exotic, which is the
+   * case it was built for: Chrome records webm/Opus, which iOS Safari cannot
+   * decode. That guarantee is preserved exactly; only the needless downgrade
+   * is gone.
    */
   private bestPresetForAsset(asset: AssetDTO, mime: string): VariantPreset {
     const order: VariantPreset[] = mime.startsWith("video/")
       ? ["video", "poster"]
       : mime.startsWith("audio/")
-        ? ["mp3", "original"] // prefer the cross-browser mp3, else the playable original; never image presets
+        ? isUniversallyPlayableAudio(mime)
+          ? ["original", "mp3"] // the upload already plays everywhere — don't hand back a re-encode
+          : ["mp3", "original"] // exotic codec: the cross-browser mp3 earns its place
         : ["lg", "md", "sm", "thumb", "xl", "original"];
     return (
       order.find((p) => hasPreset(asset, p)) ?? this.defaultPresetForMime(mime)

package/src/server/index.ts

@@ -75,49 +75,102 @@ export class NitidaClient extends BaseNitidaClient {
   }
 }
 
+// ---------------------------------------------------------------------------
+// This subpath MIRRORS THE ROOT. Every export of `@nitida/sdk` is here.
+//
+// It is a COMPLETE entry point, not an additive module — a Node consumer is
+// told to import from here and must never have to reach past it. It did:
+// `getHlsLadder` was on the root and missing here, an example in the docs
+// imported it from `/server`, and an agent evaluating the SDK got a
+// SyntaxError at RUNTIME. Measured on 2026-08-21, this list was short by 28
+// of the root's 72 — the whole palette family, every slot helper, the HLS
+// ladder helpers and the preset constants.
+//
+// The completeness is now ASSERTED by scripts/check-published-doc-symbols.ts,
+// which also owns the deny list: an omission has to be justified there, in
+// writing, or the build fails. Do not hand-edit this list to be shorter.
+// ---------------------------------------------------------------------------
 export {
   type AssetDTO,
+  type AssetPalette,
   type AssetVariant,
+  accessMessage,
+  assertPublic,
+  bestTextContrast,
   type ComposeMarketingComposition,
   type ComposeMarketingOptions,
   type ComposeMarketingResult,
   type ComposeMarketingSegment,
   type CompressOptions,
-  // URL builders & related types (re-export from asset-client via root).
   computeVariantDimensions,
+  configureSlotResolver,
+  contrastRatio,
+  deriveAccessKey,
   extractAssetSha,
+  getAmbientGradient,
   getAssetDimensions,
   getAssetSrcSet,
   getAssetUrl,
+  getCdnBase,
+  getHlsLadder,
   getHlsStreamingUrl,
+  getPaletteBlurBackground,
+  getPaletteCssVars,
+  getPrivateAssetUrl,
+  getPrivateTransformUrl,
   getSignedTransformUrl,
   getTenantId,
+  getTextColorForBackground,
   getTransformSrcSet,
   getTransformUrl,
   getVideoTransformUrl,
+  type HlsRung,
   hasPreset,
+  hlsLadderAlignment,
+  invalidateSlotCache,
+  isUniversallyPlayableAudio,
+  iteratePaletteSwatches,
+  mimeFromFileName,
   type NitidaClientOptions,
+  type PaletteSwatch,
+  PRESET_EXT,
+  PRESET_LONG,
+  PRESET_MAX_DIM,
+  PRESET_SHORT,
   type PresignUploadUrlOptions,
+  pickAmbientBackground,
   type RegenerateResult,
+  type RequestablePreset,
   type ResolveSlotOptions,
+  relativeLuminance,
+  resolveSlot,
+  resolveSlots,
+  type SignAccessOptions,
   type SignedTransformOptions,
   type SlotDTO,
   type SlotHistoryEntry,
   type SlotResolution,
   serializeTransform,
+  setCdnBase,
   setTenantId,
+  signAccessUrl,
   signTransformUrl,
+  TRANSFORM_WIDTHS,
   type TransformEffect,
   type TransformFit,
   type TransformFormat,
   type TransformGravity,
   type TransformOptions,
+  type TransformWidth,
   type UploadOptions,
   type UploadResult,
   type UploadUrlResult,
+  type UploadVideoOptions,
   type UsageDailyPoint,
   type UsagePerKey,
   type UsageSnapshot,
   type UsageWindow,
+  type VariantEntryPreset,
   type VariantPreset,
+  type VisibilityHint,
 } from "..";