@nitida/sdk 0.35.0 → 0.36.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nitida/sdk",
-  "version": "0.35.0",
+  "version": "0.36.1",
   "description": "nitida — the media SDK: browser and mobile upload with resume, client-side compression, on-the-fly transforms behind a CDN, video transcode, HLS ladders and AI proxies. Multi-tenant.",
   "private": false,
   "publishConfig": {
@@ -73,7 +73,7 @@
   },
   "peerDependencies": {
     "react": ">=18",
-    "@nitida/asset-client": "^0.23.0",
+    "@nitida/asset-client": "^0.24.0",
     "@nitida/asset-compressor-web": "^0.6.1",
     "@nitida/asset-compressor-native": "^0.2.1"
   },

package/skills/nitida-sdk/SKILL.md

@@ -190,11 +190,24 @@ everyone, and the ladder buys you nothing.
 
 > Full measurements, with the method: <https://nitida.gofuture.space/guides/transform-benchmark/>
 
-`/t/` short-circuits to the smallest **stored variant** that covers the request
-— and that variant is already a WebP
-that went through one lossy pass. **The short-circuit only fires when the
-request carries an explicit numeric `quality`**, so **passing any explicit numeric `quality` at all** is
-exactly what turns it on.
+`/t/` can short-circuit to the smallest **stored variant** that covers the request
+— and that variant is already a WebP that went through one lossy pass.
+
+🔴 **Until 2026-08-31 that shortcut fired on `typeof quality === "number"`**, so
+the parameter named "quality" was the one that chose WHICH BYTES to decode, and
+pinning it *lowered* quality. **That is fixed at the server.** `quality` now only
+sets the encoder; the cheap source has to be asked for by name, `source=nearest`
+(default `master`), and a bogus value is a 400.
+
+Verified against production the day it shipped, same asset, cold DSLs:
+`quality=61` → `x-transform-source: lg` before · `quality=62` → `original` after ·
+`quality=64,source=nearest` → `lg`, deliberately.
+
+⇒ **You cannot trigger a second lossy pass by accident any more.** The numbers
+below are the honest cost of one, i.e. what `source=nearest` buys today. And
+`source` is deliberately NOT in `TransformOptions`: the only legitimate consumer
+is a bulk pipeline that hand-builds URLs, and keeping it off the typed surface is
+what stops an ordinary caller from landing there.
 
 Measured at `width=800` on five photographs, same photo uploaded twice (full
 ladder vs `["original"]` only):
@@ -215,7 +228,16 @@ Smaller **and** worse is generation loss, not a saving.
   so there is no downscale in between to hide the first pass. At 640 and 1920
   the laddered output is *heavier* too.
 - **`["original"]`-only assets are unaffected** — one pass, always.
-- **`quality: "auto"` is a NO-OP** — byte-for-byte identical to omitting the key.
+- 🔴 **Since `@nitida/asset-client` 0.24.0 you CANNOT pass it.** `quality` is gone from
+  `TransformOptions`, so `getTransformUrl(a, { width, quality: 75 })` is a **compile error**.
+  There is nothing to remember and nothing to get wrong. If you are reading older code or older
+  docs that pass it, that code no longer compiles — delete the key, do not look for a replacement.
+- **The one narrow legitimate case has its own door, and it cannot be called blind:**
+  `getByteBudgetTransformUrl(asset, { …, quality })`. It requires a `presets` string on the asset
+  (a bare `{ sha }` does not compile) and **throws** if the asset has any size variant, or if
+  `presets` is missing — *unknown is not permission*. Use it only for a byte budget somebody
+  measured, on an asset uploaded `presets: ["original"]`.
+- **`quality: "auto"` was a NO-OP** — byte-for-byte identical to omitting the key.
   Measured 2026-08-31 on a production laddered asset at `width=1920`: both
   answered **136 680 B, sha256 `3a9ba57d…`, `x-transform-source: original`**.
   ⇒ The whole option is unnecessary, which is why `TransformOptions.quality`

package/src/index.ts

@@ -265,6 +265,7 @@ export {
   getHlsStreamingUrl,
   getPaletteBlurBackground,
   getPaletteCssVars,
+  getByteBudgetTransformUrl,
   getPrivateAssetUrl,
   getPrivateTransformUrl,
   getSignedTransformUrl,
@@ -274,6 +275,7 @@ export {
   getTransformUrl,
   getVideoTransformUrl,
   hasPreset,
+  hasSizeLadder,
   hlsLadderAlignment,
   invalidateSlotCache,
   isRequestablePreset,

package/src/server/index.ts

@@ -120,6 +120,7 @@ export {
   getPaletteCssVars,
   getPrivateAssetUrl,
   getPrivateTransformUrl,
+  getByteBudgetTransformUrl,
   getSignedTransformUrl,
   getTenantId,
   getTextColorForBackground,
@@ -128,6 +129,7 @@ export {
   getVideoTransformUrl,
   type HlsRung,
   hasPreset,
+  hasSizeLadder,
   hlsLadderAlignment,
   invalidateSlotCache,
   isRequestablePreset,

package/src/web/index.ts

@@ -137,6 +137,7 @@ export {
   getPaletteCssVars,
   getPrivateAssetUrl,
   getPrivateTransformUrl,
+  getByteBudgetTransformUrl,
   getSignedTransformUrl,
   getTenantId,
   getTextColorForBackground,
@@ -145,6 +146,7 @@ export {
   getVideoTransformUrl,
   type HlsRung,
   hasPreset,
+  hasSizeLadder,
   hlsLadderAlignment,
   invalidateSlotCache,
   isRequestablePreset,