@nitida/sdk 0.31.4 → 0.31.5

package/README.md

@@ -883,7 +883,20 @@ const asset = await aq.assets.byHash(sha256);
 > outside `TransformWidth`. Need an arbitrary one? **Sign it** —
 > `aq.transform(asset, { width: 1490 }, { sign: true })` and `getSignedTransformUrl` take
 > `SignedTransformOptions` (where `width` widens to `number`); a valid `?sig=` earns the
-> edge-whitelist bypass. `transformSrcSet` / `getTransformSrcSet` deliberately keep
+> edge-whitelist bypass.
+>
+> ⚠️ **Signed widths have two ceilings the edge does not announce** (measured
+> 2026-08-24):
+>
+> 1. **7680 is the hard cap.** `7680` → 200, `7681` → 400. Unsigned, the real
+>    cap is 3840 — so `3841…4320` is a dead band the old 400 message called
+>    "in range", and `4321…7680` works signed while that message called it
+>    impossible.
+> 2. **Above the source width it CLAMPS and still answers 200.** `/t/` never
+>    upscales. Ask for 5000 on an 800 px master and you get **800 px of bytes
+>    with HTTP 200** — no error, no warning. Read `x-transform-dsl` on the
+>    response (it names the width actually used) or size against the source, if
+>    the exact width matters. `transformSrcSet` / `getTransformSrcSet` deliberately keep
 > `number[]` because a responsive ladder may legitimately include DPR-row widths (e.g.
 > `2400`). `height` stays `number` — for the responsive path it's derived from `width`
 > by aspect ratio; only fixed-canvas crops / `genfill` set it explicitly.
@@ -897,8 +910,14 @@ point of asking for `auto` instead of naming a format.
 `gravity=face` detects the highest-confidence face and crops to it with
 sensible padding (50 % of face dimensions on each side, clamped to source
 bounds, keeping the requested aspect ratio). When no face is detected it
-falls back to saliency-based cropping and returns the response with
-`X-Transform-Face: fallback`, so you can tell the two apart. Cost to you:
+falls back to saliency-based cropping. The response **always** carries
+`X-Transform-Face`, with one of two values: **`matched`** when a face was found,
+**`fallback`** when it saliency-cropped.
+
+⚠️ Check the VALUE, not the presence. The header is emitted **only for
+`gravity=face`** — with `center` or `auto` it is absent, and that absence does
+not mean "no face". Code that tests for presence is right 0 % of the time on
+photos that do contain a face. Cost to you:
 ~10 ms warm; ~150 ms on the first request after a cold start.
 
 `quality=auto` adapts the per-format quality to source complexity
@@ -1186,6 +1205,18 @@ landscape source ✓). For bigger crops, prefer `gravity=auto` smart-crop,
 which is deterministic and free — no generation, no invention.
 
 **What it costs you: ~$0.05 for the first request** per (sha, dsl, format)
+⚠️ **The signature guards GENERATION, not DELIVERY.** Once a signed transform
+runs, its result is written to `/{tenant}/v/<sha>-t<dslHash>.<ext>` and served
+there **with HTTP 200 and no `?sig=`**. `<dslHash>` is `sha256(canonical DSL)`
+truncated to 16 — **no secret in it**, so anyone who guesses the DSL derives the
+URL. Measured: a signed `width=641` (unreachable unsigned) went from 404 to 200
+at the derived path after a single signed GET.
+
+Two consequences worth planning around: turning on `strict_transforms` does not
+un-publish anything already generated, and for `genfill` — whose entire cost
+guard is the signature — the result you paid for stays publicly readable. Treat
+a signed transform as "pay once, publish forever", not as an access control.
+
 tuple. Subsequent identical requests are 302 redirects to the cached WebP —
 zero generative cost, forever. The model is server-side and may be swapped
 for a better one without any change on your side; the DSL, the output and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nitida/sdk",
-  "version": "0.31.4",
+  "version": "0.31.5",
   "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": {