@nitida/sdk 0.36.2 → 0.37.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nitida/sdk",
-  "version": "0.36.2",
+  "version": "0.37.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.24.0",
+    "@nitida/asset-client": "^0.25.0",
     "@nitida/asset-compressor-web": "^0.6.1",
     "@nitida/asset-compressor-native": "^0.2.1"
   },

package/skills/nitida-sdk/SKILL.md

@@ -186,6 +186,26 @@ everyone, and the ladder buys you nothing.
 - ⚠️ The **first** request of each width is generated cold, then cached at the
   edge immutably. Warm them after upload if the first visitor matters.
 
+### `xl` is the base itself when the base is already ≤ 4K
+
+4K (3840 px long side) is the cap for listing photos, and a base inside it is
+already final. So at upload the server stores a **clean WebP base ≤ 3840 px**
+(single frame, no EXIF orientation, no EXIF/XMP block) as `xl`
+**byte-identical**: same sha256, no decode, no second lossy pass. Anything else
+is re-encoded to WebP q82 as before: a base larger than 3840 px (resized to
+3840), a JPEG/PNG/HEIC, an animated WebP, or a WebP carrying EXIF/XMP (the
+re-encode strips metadata, so GPS never reaches a public URL).
+
+- The default browser compressor (`compressImage`, 3840 px WebP via canvas,
+  which writes no EXIF) produces exactly such a base. Upload with `"xl"` in
+  `presets` and `xl` costs no quality.
+- URLs, keys (`…/x/<sha>.webp`), `presets` and response shapes are unchanged.
+  `xl` is still its own stored object (a copy of the base's bytes), so it
+  weighs the same as the base, not less.
+- This applies to uploads processed on or after the server change. Assets
+  already stored keep the `xl` they have. `regenerate(id, { presets: ["xl"] })`
+  applies the new rule.
+
 ### ⚠️⚠️ On a LADDERED asset, an explicit `quality` compresses the image TWICE
 
 > Full measurements, with the method: <https://nitida.gofuture.space/guides/transform-benchmark/>

package/src/index.ts

@@ -59,6 +59,7 @@ import {
   type SignTransformOptions,
   type SlotDTO,
   type SlotResolution,
+  type ImageRole,
   setCdnBase,
   setTenantId,
   type TransformOptions,
@@ -241,6 +242,7 @@ export type {
   TransformGravity,
   TransformOptions,
   TransformWidth,
+  ImageRole,
   VariantEntryPreset,
   VariantPreset,
   VisibilityHint,
@@ -298,6 +300,12 @@ export {
   signAccessUrl,
   signTransformUrl,
   TRANSFORM_WIDTHS,
+  getRoleLadder,
+  getRolesLadder,
+  IMAGE_LADDER,
+  IMAGE_ROLE_LADDERS,
+  IMAGE_ROLES,
+  isImageRole,
   toRequestablePresets,
   transformMessage,
 } from "@nitida/asset-client";
@@ -534,6 +542,14 @@ export type PresignUploadUrlOptions = {
   clientOriginalBytes?: number;
   /** VIDEO-only delivery knobs forwarded into `/assets/process`. See {@link UploadVideoOptions}. */
   video?: UploadVideoOptions;
+  /**
+   * Image roles whose transform ladder (`IMAGE_ROLE_LADDERS`) the platform warms
+   * at the CDN edge once the asset is ready, so the first visitor does not pay
+   * a cold encode. Omit to warm nothing. Ignored for non-images and when the
+   * bytes were already stored (a deduped upload runs no processing; use the
+   * backfill for those).
+   */
+  warm?: ImageRole[];
 };
 
 /** Input shape accepted by `aq.assets.composeMarketing(...)`. */
@@ -794,6 +810,7 @@ class AssetsApi {
     if (opts.clientOriginalBytes != null)
       body.clientOriginalBytes = opts.clientOriginalBytes;
     if (opts.video != null) body.video = opts.video;
+    if (opts.warm && opts.warm.length > 0) body.warm = opts.warm;
 
     const r = await fetch(endpointHref(this.opts, "/assets/upload-url"), {
       method: "POST",
@@ -1075,6 +1092,14 @@ export type UploadOptions = {
    * any audio original — and asking for either is a 400.
    */
   presets?: RequestablePreset[];
+  /**
+   * Image roles whose transform ladder (`IMAGE_ROLE_LADDERS`) the platform warms
+   * at the CDN edge once the asset is ready, so the first visitor does not pay
+   * a cold encode. Omit to warm nothing. Ignored for non-images and when the
+   * bytes were already stored (a deduped upload runs no processing; use the
+   * backfill for those).
+   */
+  warm?: ImageRole[];
   /**
    * 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
@@ -1848,6 +1873,7 @@ export class NitidaClient {
           : DEFAULT_UPLOAD_PRESETS,
       ...(clientOriginalBytes != null && { clientOriginalBytes }),
       ...(opts.video != null && { video: opts.video }),
+      ...(opts.warm && opts.warm.length > 0 && { warm: opts.warm }),
     });
     if (presign.deduped) {
       const short = sha.slice(0, 16);

package/src/server/index.ts

@@ -167,12 +167,19 @@ export {
   signAccessUrl,
   signTransformUrl,
   TRANSFORM_WIDTHS,
+  getRoleLadder,
+  getRolesLadder,
+  IMAGE_LADDER,
+  IMAGE_ROLE_LADDERS,
+  IMAGE_ROLES,
+  isImageRole,
   type TransformEffect,
   type TransformFit,
   type TransformFormat,
   type TransformGravity,
   type TransformOptions,
   type TransformWidth,
+  type ImageRole,
   toRequestablePresets,
   transformMessage,
   type UploadOptions,

package/src/web/index.ts

@@ -193,12 +193,19 @@ export {
   signAccessUrl,
   signTransformUrl,
   TRANSFORM_WIDTHS,
+  getRoleLadder,
+  getRolesLadder,
+  IMAGE_LADDER,
+  IMAGE_ROLE_LADDERS,
+  IMAGE_ROLES,
+  isImageRole,
   type TransformEffect,
   type TransformFit,
   type TransformFormat,
   type TransformGravity,
   type TransformOptions,
   type TransformWidth,
+  type ImageRole,
   toRequestablePresets,
   transformMessage,
   type UploadOptions,