@nitida/sdk 0.33.0 → 0.36.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nitida/sdk",
-  "version": "0.33.0",
+  "version": "0.36.0",
   "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.21.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

@@ -94,7 +94,16 @@ 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` (`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.)
+⚠️ **Widths MUST be on the unsigned ladder** `TRANSFORM_WIDTHS` — generated from the source, do not
+edit by hand:
+
+<!-- BEGIN GENERATED: transform-widths · bun run gen:docs -->
+`96, 128, 160, 180, 240, 256, 320, 400, 480, 600, 640, 800, 960, 1080, 1200, 1280, 1440, 1600, 1920, 2560, 3840` — 21 widths.
+<!-- END GENERATED: transform-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.)
 
 ⚠️ **`getTransformSrcSet` is NOT protected by that type.** Its parameter is `number[]` on purpose —
 a responsive ladder may legitimately carry DPR widths — so `[641, 999]` compiles clean and fails in
@@ -206,6 +215,52 @@ 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.
+- 🔴 **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`
+  carries an `@deprecated` tag since `@nitida/asset-client` 0.23.0. Your editor
+  strikes it through; that is on purpose.
+- **A second corpus, where there is not even a byte saving.** 5056 px
+  architectural renders (tenant `suenos-del-mar`, 2026-08-31), referenced
+  against `/t/format=png,width=W/` — the lossless auto path at the same width:
+
+  | width | pinned source | bytes | PSNR |
+  |---|---|---|---|
+  | 3840 | `xl` | **+7.2 %** | **−0.50 dB** |
+  | 1920 | `lg` | **+8.1 %** | **−0.64 dB** |
+  | 1280 | `md` | **+2.0 %** | **−0.85 dB** |
+
+  Heavier **and** worse, 3 of 3. The photograph corpus above at least came back
+  smaller — that is exactly what hid this for four months.
+
+### ✅ The one-line check: `x-transform-source`
+
+**Do not reason about which path you got — read it off the response.** The
+header names the variant the edge actually decoded:
+
+```bash
+curl -sI 'https://8ok.uk/t/format=webp,width=1920/<sha16>.webp' \
+  | grep -i x-transform-source
+```
+
+| it says | you got |
+|---|---|
+| `original` | **one** lossy pass ✅ |
+| `md` / `lg` / `xl` / `sm` | **two** — a numeric `quality` is in your URL ✖ |
+| `poster` | you asked `/t/` for a video sha; it transformed the poster frame |
+
+Run it once per surface after a change. It costs nothing and it is the only
+statement about compression that is not an inference.
 
 ### What running this recipe caught
 
@@ -602,7 +657,13 @@ await getPrivateTransformUrl(asset, { width: 1280 }, signingKey, { expiresInSeco
   `"public"`, or a bare `{ sha }`, is never refused — and this is a DIFFERENT
   rule from the missing-preset fallback below, which is about presets, not
   privacy.
-- **`exp` is mandatory**; revocation is *"within a minute"* (60 s TTL at the edge).
+- **`exp` is mandatory and CAPPED at 7 days.** `expiresInSeconds` over that
+  throws in the SDK and 401s (`exp_too_far`) at the platform — an expiry that
+  never arrives is not an expiry. Revocation is *"within a minute"* (60 s TTL
+  at the edge).
+- **⚠️ A signature does NOT widen the width ladder.** Off-ladder widths are 400
+  whether or not the URL is signed. Signing buys IDENTITY (which tenant asked,
+  until `exp`), which is what `strict_transforms` and `effect=genfill` need.
 - **The signing key is a backend secret** — it mints URLs for every private
   asset the tenant owns.
 - **⭐ Where the signing key comes from: the response that CREATED your
@@ -610,10 +671,15 @@ await getPrivateTransformUrl(asset, { width: 1280 }, signingKey, { expiresInSeco
   three API keys, and the console shows it in the same panel. Nothing else
   hands it out — `GET /admin/projects/:code` does **not** include it. If it is
   lost, the only endpoint that returns a key is
-  `POST /admin/projects/:code/rotate-signing-key`, which **invalidates every
-  URL already signed** and needs the system-scope key the platform operator
-  holds. A tenant with nothing signed yet can rotate for free; a live one
-  cannot, which is why you save it at creation.
+  `POST /admin/projects/:code/rotate-signing-key`, and it needs the
+  system-scope key the platform operator holds.
+- **⭐ Rotating no longer kills your `/t/` URLs.** Since `@nitida/sdk` 0.31.0 a
+  signed transform URL carries `kid` (which key signed it) and `exp`, and the
+  OUTGOING key keeps verifying for 14 days after a rotation. ⚠️ The exception
+  is `/a/…` ACCESS URLs: their key is derived from `signing_key` with no `kid`,
+  so those 401 immediately on rotation. They are minted per view with
+  minute-scale expiries, so the burst heals itself — but rotate at a quiet hour
+  if the tenant serves private assets.
 - **⭐ Already have a project and never saw a signing key?** Then you never got
   one — projects created before 2026-08-23 were not handed it, and no endpoint
   shows you the current one. **If you have not signed any URLs yet, ask us to
@@ -622,6 +688,69 @@ await getPrivateTransformUrl(asset, { width: 1280 }, signingKey, { expiresInSeco
   instead. This is the wall the T5 agent hit, and the sentence that was
   missing.
 
+## ⚠️ EXIF orientation — two dimension pairs, and mixing them stretches the photo
+
+**A phone taking a portrait photo does not store portrait pixels.** It writes the
+sensor buffer landscape and tags it `Orientation` 5–8 meaning "rotate before
+showing". So every such file has **two** pairs, transposes of each other:
+
+```
+4032×3024   the STORED buffer (what a header parser reads)
+3024×4032   what it DISPLAYS as (what every decoder hands you)
+```
+
+Use the **stored** pair only for orientation-invariant quantities — area, a
+megapixel budget. Use the **displayed** pair for anything geometric: a resize
+target, an aspect ratio, a layout box, a coordinate you denormalise.
+
+**This exact confusion shipped twice, on both sides of the wire:**
+
+| where | what happened | fixed |
+|---|---|---|
+| `@nitida/asset-compressor-web` 0.6.0–0.6.2 | resize target from the stored pair, fed to a decode that had already rotated ⇒ **1.78× stretch**, measured | **0.6.3** |
+| `asset-manager` (server), until 2026-08-28 | recorded the stored pair as the asset's `w`/`h` while serving rotated variants ⇒ transposed aspect on the DTO | 2026-08-28 |
+
+Needed all three, which is why it looked random: a parseable header
+(**HEIC is immune** — the ISOBMFF box walk isn't implemented, so no dims, so no
+forced resize), orientation **5–8**, and a long side **above** the box.
+
+⇒ **Damage is pre-upload and unrecoverable.** The raw bucket faithfully stores the
+already-stretched bytes. Affected photos must be re-uploaded from the original;
+no backfill exists.
+
+### The two traps, concretely
+
+**Browser — `createImageBitmap` with BOTH resize axes does not preserve ratio.**
+
+```ts
+// 🔴 any disagreement with the decoded bitmap becomes a stretch
+createImageBitmap(blob, { imageOrientation: "from-image", resizeWidth: w, resizeHeight: h })
+// ✅ one axis: the spec derives the other, ratio survives BY CONSTRUCTION
+createImageBitmap(blob, { imageOrientation: "from-image", resizeWidth: w })
+```
+
+**Node — `sharp(x).rotate().metadata()` does NOT apply the rotation.** `.rotate()`
+queues an operation; `.metadata()` still reads the input. Measured, sharp 0.34.5:
+
+```
+sharp(buf).metadata()                     → 4032×3024, orientation 6
+sharp(buf).rotate().metadata()            → 4032×3024   ← the false idiom
+sharp(buf).rotate().toBuffer() → info     → 3024×4032   ← the truth
+```
+
+It read so plausibly it was written three times in one repo, once directly under
+the comment *"Source dims (EXIF-rotated for correctness)"*. To get display dims:
+transpose the raw pair yourself when `orientation` is 5–8, or measure the output
+buffer.
+
+**And the lesson that cost the most:** the stretch had been suspected once and
+declared *"refuted with production data"* because storage held four distinct
+aspect ratios — "a pipeline that forced a ratio would have produced ONE". It
+never forced one ratio; it forced **each photo's own transpose**. Counting
+distinct ratios could not detect it, so finding several was evidence of nothing.
+**An invariant you cannot state is an invariant you cannot test** — compare
+against the *displayed* ratio, or you are comparing stored ratios to each other.
+
 ## 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:
@@ -696,6 +825,8 @@ needed. Reproduce there before debugging any of these by hand.
 
 | Symptom | Cause |
 |---|---|
+| **a portrait photo comes back stretched wide**, and only some do | `@nitida/asset-compressor-web` **0.6.0–0.6.2**: stored (pre-EXIF) dims forced onto an already-rotated decode ⇒ 1.78×. Needs a parseable header (**HEIC immune**) + orientation 5–8 + long side above the box. **Fixed in 0.6.3**; pre-upload damage, so re-upload, don't repair — see §EXIF orientation |
+| **`w`/`h` on the DTO disagree with the image you receive** | `asset-manager` older than 2026-08-28 recorded the stored pair for EXIF-rotated sources. The **variant** dims were always right — trust those until the asset is re-processed |
 | **400** on an image URL | width not on `TRANSFORM_WIDTHS` ladder |
 | **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/` |

package/src/index.ts

@@ -49,17 +49,20 @@ import {
   hasPreset,
   invalidateSlotCache,
   isRequestablePreset,
+  type PrivateTransformOptions,
   REQUESTABLE_PRESETS,
   type RequestablePreset,
   type ResolveSlotOptions,
   resolveSlot,
   resolveSlots,
   type SignedTransformOptions,
+  type SignTransformOptions,
   type SlotDTO,
   type SlotResolution,
   setCdnBase,
   setTenantId,
   type TransformOptions,
+  type TransformWidth,
   toRequestablePresets,
   type VariantEntryPreset,
   type VariantPreset,
@@ -224,10 +227,12 @@ export type {
   AssetVariant,
   HlsRung,
   PaletteSwatch,
+  PrivateTransformOptions,
   RequestablePreset,
   ResolveSlotOptions,
   SignAccessOptions,
   SignedTransformOptions,
+  SignTransformOptions,
   SlotDTO,
   SlotResolution,
   TransformEffect,
@@ -249,6 +254,7 @@ export {
   configureSlotResolver,
   contrastRatio,
   deriveAccessKey,
+  deriveTransformKid,
   extractAssetSha,
   getAmbientGradient,
   getAssetDimensions,
@@ -259,6 +265,7 @@ export {
   getHlsStreamingUrl,
   getPaletteBlurBackground,
   getPaletteCssVars,
+  getByteBudgetTransformUrl,
   getPrivateAssetUrl,
   getPrivateTransformUrl,
   getSignedTransformUrl,
@@ -268,10 +275,14 @@ export {
   getTransformUrl,
   getVideoTransformUrl,
   hasPreset,
+  hasSizeLadder,
   hlsLadderAlignment,
   invalidateSlotCache,
   isRequestablePreset,
   iteratePaletteSwatches,
+  MAX_SIGNED_TRANSFORM_TTL_SECONDS,
+  MAX_SIGNED_URL_TTL_SECONDS,
+  MIN_SIGNED_TRANSFORM_TTL_SECONDS,
   PRESET_EXT,
   PRESET_LONG,
   PRESET_MAX_DIM,
@@ -288,6 +299,7 @@ export {
   signTransformUrl,
   TRANSFORM_WIDTHS,
   toRequestablePresets,
+  transformMessage,
 } from "@nitida/asset-client";
 
 // ---------------------------------------------------------------------------
@@ -1477,27 +1489,21 @@ export class NitidaClient {
    */
   // Overload 1: no signing — synchronous, on-ladder width only (strict).
   transform(asset: Pick<AssetDTO, "sha">, opts?: TransformOptions): string;
-  // Overload 2: with { sign: true } — async; returns `?sig=<hmac>` URL.
-  // Accepts SignedTransformOptions so a signed URL may carry an off-ladder
-  // custom width (the signature earns the edge whitelist bypass).
+  // Overload 2: with { sign: true, expiresInSeconds } — async; returns a
+  // `?kid&exp&sig` URL. The width ladder is the SAME as unsigned: a signature
+  // names the caller, it does not widen the image (doc blindaje WS-6).
   transform(
     asset: Pick<AssetDTO, "sha">,
     opts: SignedTransformOptions,
-    signOpts: { sign: true },
+    signOpts: { sign: true } & SignTransformOptions,
   ): Promise<string>;
   transform(
     asset: Pick<AssetDTO, "sha">,
     opts: SignedTransformOptions = {},
-    signOpts?: { sign: true },
+    signOpts?: { sign: true } & SignTransformOptions,
   ): string | Promise<string> {
     if (!signOpts?.sign) {
-      // Unsigned path. Overload 1 constrains `width` to the ladder at every
-      // public call site, so an off-ladder width can't reach here through the
-      // typed API — narrow back to TransformOptions for the strict builder.
-      return (
-        getTransformUrl(asset, opts as TransformOptions) ??
-        this.urlFor(asset, "lg")
-      );
+      return getTransformUrl(asset, opts) ?? this.urlFor(asset, "lg");
     }
     if (!this.opts.signingKey) {
       throw new Error(
@@ -1505,11 +1511,15 @@ export class NitidaClient {
           "No signingKey on this client. It is returned ONCE, in the response that creates your project (POST /admin/projects → `signingKey`, next to the three API keys; the console shows it in the same panel). If you never saw one — projects created before 2026-08-23 were not handed it — ask the platform operator to rotate: with no signed URLs in flight that invalidates nothing and is free. If you DO have signed URLs circulating, ask for the current key instead, because rotating would kill them. Then pass it to the SDK constructor on a SERVER-side instance only.",
       );
     }
-    // Signed path — custom (off-ladder) widths allowed. Empty opts → no
-    // transform DSL, fall back to the unsigned `lg` variant URL.
+    // Empty opts → no transform DSL, fall back to the unsigned `lg` variant
+    // URL. `tenantId` defaults to the one this client was constructed with,
+    // because the tenant is part of the signed message.
     return (
-      getSignedTransformUrl(asset, opts, this.opts.signingKey) ??
-      Promise.resolve(this.urlFor(asset, "lg"))
+      getSignedTransformUrl(asset, opts, this.opts.signingKey, {
+        expiresInSeconds: signOpts.expiresInSeconds,
+        tenantId: signOpts.tenantId ?? this.opts.tenantId,
+        nowSeconds: signOpts.nowSeconds,
+      }) ?? Promise.resolve(this.urlFor(asset, "lg"))
     );
   }
 
@@ -1527,15 +1537,15 @@ export class NitidaClient {
   ): string;
   transformSrcSet(
     asset: Pick<AssetDTO, "sha">,
-    widths: number[],
+    widths: TransformWidth[],
     extraOpts: Omit<TransformOptions, "width">,
-    signOpts: { sign: true },
+    signOpts: { sign: true } & SignTransformOptions,
   ): Promise<string>;
   transformSrcSet(
     asset: Pick<AssetDTO, "sha">,
     widths: number[],
     extraOpts: Omit<TransformOptions, "width"> = {},
-    signOpts?: { sign: true },
+    signOpts?: { sign: true } & SignTransformOptions,
   ): string | Promise<string> {
     if (!signOpts?.sign) return getTransformSrcSet(asset, widths, extraOpts);
     if (!this.opts.signingKey) {
@@ -1545,15 +1555,22 @@ export class NitidaClient {
       );
     }
     const key = this.opts.signingKey;
+    const sign = {
+      expiresInSeconds: signOpts.expiresInSeconds,
+      tenantId: signOpts.tenantId ?? this.opts.tenantId,
+      nowSeconds: signOpts.nowSeconds,
+    };
     return Promise.all(
       widths.map(async (w) => {
-        // Signed path → off-ladder widths allowed; build+sign via the
-        // custom-width helper (the strict `getTransformUrl` would reject a
-        // raw `number` width).
+        // ⚠️ The overload types `widths` as `TransformWidth[]` on the signed
+        // path. Off-ladder widths 400 at the edge whether or not they are
+        // signed (doc blindaje WS-6), so a signed srcSet full of custom widths
+        // is a srcSet of 400s — the type says so at compile time now.
         const signed = await getSignedTransformUrl(
           asset,
-          { ...extraOpts, width: w },
+          { ...extraOpts, width: w as TransformWidth },
           key,
+          sign,
         );
         return signed ? `${signed} ${w}w` : null;
       }),

package/src/server/index.ts

@@ -107,6 +107,7 @@ export {
   configureSlotResolver,
   contrastRatio,
   deriveAccessKey,
+  deriveTransformKid,
   extractAssetSha,
   getAmbientGradient,
   getAssetDimensions,
@@ -119,6 +120,7 @@ export {
   getPaletteCssVars,
   getPrivateAssetUrl,
   getPrivateTransformUrl,
+  getByteBudgetTransformUrl,
   getSignedTransformUrl,
   getTenantId,
   getTextColorForBackground,
@@ -127,11 +129,15 @@ export {
   getVideoTransformUrl,
   type HlsRung,
   hasPreset,
+  hasSizeLadder,
   hlsLadderAlignment,
   invalidateSlotCache,
   isRequestablePreset,
   isUniversallyPlayableAudio,
   iteratePaletteSwatches,
+  MAX_SIGNED_TRANSFORM_TTL_SECONDS,
+  MAX_SIGNED_URL_TTL_SECONDS,
+  MIN_SIGNED_TRANSFORM_TTL_SECONDS,
   mimeFromFileName,
   type NitidaClientOptions,
   type PaletteSwatch,
@@ -140,6 +146,7 @@ export {
   PRESET_MAX_DIM,
   PRESET_SHORT,
   type PresignUploadUrlOptions,
+  type PrivateTransformOptions,
   pickAmbientBackground,
   REQUESTABLE_PRESETS,
   type RegenerateResult,
@@ -150,6 +157,7 @@ export {
   resolveSlots,
   type SignAccessOptions,
   type SignedTransformOptions,
+  type SignTransformOptions,
   type SlotDTO,
   type SlotHistoryEntry,
   type SlotResolution,
@@ -166,6 +174,7 @@ export {
   type TransformOptions,
   type TransformWidth,
   toRequestablePresets,
+  transformMessage,
   type UploadOptions,
   type UploadResult,
   type UploadUrlResult,

package/src/web/index.ts

@@ -124,6 +124,7 @@ export {
   configureSlotResolver,
   contrastRatio,
   deriveAccessKey,
+  deriveTransformKid,
   extractAssetSha,
   getAmbientGradient,
   getAssetDimensions,
@@ -136,6 +137,7 @@ export {
   getPaletteCssVars,
   getPrivateAssetUrl,
   getPrivateTransformUrl,
+  getByteBudgetTransformUrl,
   getSignedTransformUrl,
   getTenantId,
   getTextColorForBackground,
@@ -144,11 +146,15 @@ export {
   getVideoTransformUrl,
   type HlsRung,
   hasPreset,
+  hasSizeLadder,
   hlsLadderAlignment,
   invalidateSlotCache,
   isRequestablePreset,
   isUniversallyPlayableAudio,
   iteratePaletteSwatches,
+  MAX_SIGNED_TRANSFORM_TTL_SECONDS,
+  MAX_SIGNED_URL_TTL_SECONDS,
+  MIN_SIGNED_TRANSFORM_TTL_SECONDS,
   mimeFromFileName,
   type PaletteSwatch,
   PRESET_EXT,
@@ -156,6 +162,7 @@ export {
   PRESET_MAX_DIM,
   PRESET_SHORT,
   type PresignUploadUrlOptions,
+  type PrivateTransformOptions,
   pickAmbientBackground,
   REQUESTABLE_PRESETS,
   type RegenerateResult,
@@ -166,6 +173,7 @@ export {
   resolveSlots,
   type SignAccessOptions,
   type SignedTransformOptions,
+  type SignTransformOptions,
   type SlotDTO,
   type SlotHistoryEntry,
   type SlotResolution,
@@ -182,6 +190,7 @@ export {
   type TransformOptions,
   type TransformWidth,
   toRequestablePresets,
+  transformMessage,
   type UploadOptions,
   type UploadResult,
   type UploadUrlResult,