@nitida/sdk 0.24.0 → 0.25.0

package/src/index.ts

@@ -4,8 +4,8 @@
  *
  * One ergonomic facade over the underlying packages
  * (`@nitida/asset-client` URL builders + `@aquienpz/asset-uploader-web`
- * + the slot resolver). Auth is a Better Auth API key (`amk_rt_*`)
- * issued by aquienpz `bootstrap-project.ts`; tenant scope comes from
+ * + the slot resolver). Auth is a bearer API key (`amk_rt_*`), issued
+ * per tenant when the tenant is created; tenant scope comes from
  * the key's metadata (`X-Tenant-Code` is log-only).
  *
  * Usage:
@@ -14,8 +14,8 @@
  *
  *   const aq = new NitidaClient({
  *     endpoint: "https://api.nitida.gofuture.space",
- *     apiKey:   process.env.ASSET_MANAGER_RUNTIME_KEY!,
- *     tenantCode: "realtyone-cr",
+ *     apiKey:   process.env.AQUIENPZ_API_KEY!,   // amk_rt_* — server-only
+ *     tenantCode: "acme-co",
  *     cdnBase: "https://8ok.uk",  // optional override
  *     tenantId: 4,                 // required for tenant-prefixed URLs
  *   });
@@ -78,7 +78,7 @@ import {
  */
 export type NitidaClientOptions = {
   /**
-   * Base URL of the aquienpz asset-manager (Cloud Run service URL).
+   * Base URL of the nitida API (e.g. `https://api.nitida.gofuture.space`).
    *
    * May be relative (e.g. `/api/am`) ONLY in browser contexts where the
    * SDK resolves it against `window.location.origin`. Node/Bun consumers
@@ -86,7 +86,7 @@ export type NitidaClientOptions = {
    */
   endpoint: string;
   /**
-   * Better Auth API key with the `amk_rt_*` prefix.
+   * Bearer API key with the `amk_rt_*` prefix.
    *
    * **Server-only.** Omit when constructing from `@nitida/sdk/web` —
    * your BFF / route handler injects the bearer header in proxy mode.
@@ -111,8 +111,8 @@ export type NitidaClientOptions = {
    * Tenant's HMAC signing key for transform URLs (Phase 3). Required
    * only when calling `aq.transform(asset, opts, { sign: true })`.
    *
-   * Generated server-side per tenant (see `infra/sql/tenants_signed_transforms.sql`);
-   * fetch via `GET /admin/tenants/:id` with an admin key. **Keep it
+   * 32 random bytes, generated server-side on tenant creation; fetch
+   * via `GET /admin/tenants/:id` with an admin key. **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.
    */
@@ -190,9 +190,19 @@ function authHeaders(opts: NitidaClientOptions): Record<string, string> {
 // Re-exports (so consumers don't double-import from asset-client)
 // ---------------------------------------------------------------------------
 
+// This barrel is COMPLETE on purpose: every public symbol of
+// `@nitida/asset-client` is reachable from `@nitida/sdk`, so a consumer never
+// has to know which of the two packages a helper happens to live in. It had
+// drifted to 30 of 53 — the gap silently included `TRANSFORM_WIDTHS` and
+// `TransformWidth`, which both READMEs tell you to import precisely so an
+// off-ladder width fails at compile time instead of returning 400, and the
+// palette helpers the README imports from here by name.
 export type {
   AssetDTO,
+  AssetPalette,
   AssetVariant,
+  HlsRung,
+  PaletteSwatch,
   ResolveSlotOptions,
   SignedTransformOptions,
   SlotDTO,
@@ -202,24 +212,47 @@ export type {
   TransformFormat,
   TransformGravity,
   TransformOptions,
+  TransformWidth,
   VariantPreset,
 } from "@nitida/asset-client";
 export {
+  bestTextContrast,
   computeVariantDimensions,
+  configureSlotResolver,
+  contrastRatio,
   extractAssetSha,
+  getAmbientGradient,
   getAssetDimensions,
   getAssetSrcSet,
   getAssetUrl,
+  getCdnBase,
+  getHlsLadder,
   getHlsStreamingUrl,
+  getPaletteBlurBackground,
+  getPaletteCssVars,
   getSignedTransformUrl,
   getTenantId,
+  getTextColorForBackground,
   getTransformSrcSet,
   getTransformUrl,
   getVideoTransformUrl,
   hasPreset,
+  hlsLadderAlignment,
+  invalidateSlotCache,
+  iteratePaletteSwatches,
+  PRESET_EXT,
+  PRESET_LONG,
+  PRESET_MAX_DIM,
+  PRESET_SHORT,
+  pickAmbientBackground,
+  relativeLuminance,
+  resolveSlot,
+  resolveSlots,
   serializeTransform,
+  setCdnBase,
   setTenantId,
   signTransformUrl,
+  TRANSFORM_WIDTHS,
 } from "@nitida/asset-client";
 
 // ---------------------------------------------------------------------------
@@ -348,8 +381,8 @@ class SlotsApi {
 /**
  * Returned by `aq.assets.regenerate(...)`. The shape varies by kind —
  * images return immediately with the merged variant list; videos
- * return a dispatch handle (the actual transcode runs in a Cloud Run
- * Job and finishes async).
+ * return a dispatch handle (the actual transcode runs in a background
+ * job and finishes async).
  */
 export type RegenerateResult =
   | {
@@ -383,7 +416,7 @@ export type RegenerateResult =
 /**
  * Wire shape returned by `POST /assets/upload-url`. Either the server
  * resolves the upload synchronously via dedup (`deduped: true` + existing
- * asset DTO) or it returns a presigned R2 PUT URL plus a `process` payload
+ * asset DTO) or it returns a presigned storage PUT URL plus a `process` payload
  * the caller must POST to `/assets/process` after the PUT lands.
  */
 export type UploadUrlResult =
@@ -403,13 +436,13 @@ export type UploadVideoOptions = {
   /**
    * `false` → skip the auto-dispatched HLS adaptive ladder (240p–2160p). Use
    * for download-only assets served as a progressive `-v.mp4` and never
-   * streamed (e.g. share-video reels) — it avoids a second Cloud Run Job no
+   * streamed (e.g. share-video reels) — it avoids a second background job no
    * one watches. Default/absent → the ladder is generated as before.
    */
   hls?: boolean;
   /**
    * `true` → when the uploaded MP4 is ALREADY web-safe (H.264 + yuv420p),
-   * re-mux the `video` variant with `-c copy` instead of re-encoding. Use for
+   * re-mux the `video` variant instead of re-encoding it. Use for
    * delivery-ready uploads (the bytes are already H.264 High / yuv420p /
    * +faststart / capped bitrate) to skip a wasteful re-encode + generational
    * quality loss. Falls back to a full re-encode automatically when the source
@@ -420,7 +453,7 @@ export type UploadVideoOptions = {
 
 /** Input shape accepted by `aq.assets.presignUploadUrl(...)`. */
 export type PresignUploadUrlOptions = {
-  /** Full sha256 (64 hex) of the bytes that will be PUT to R2. */
+  /** Full sha256 (64 hex) of the bytes that will be PUT to storage. */
   sha256: string;
   /** MIME type of the bytes (e.g. `image/jpeg`, `video/mp4`). */
   mime: string;
@@ -435,8 +468,8 @@ export type PresignUploadUrlOptions = {
   presets?: VariantPreset[];
   /**
    * Pre-compression size of the source (useful when the browser ran
-   * compressorjs / heic2any before computing `bytes`). Surfaces in admin
-   * dashboards under `assets.client_original_bytes`.
+   * compressorjs / heic2any before computing `bytes`). Recorded
+   * server-side, so the savings show up in the admin usage dashboards.
    */
   clientOriginalBytes?: number;
   /** VIDEO-only delivery knobs forwarded into `/assets/process`. See {@link UploadVideoOptions}. */
@@ -571,8 +604,8 @@ class AssetsApi {
    *   const v = await aq.assets.variants(logoId);
    *   v.map((x) => x.preset);  // → ("thumb" | "sm" | … | "original")[]
    *
-   * ⚠️ Returns `[]` — not an error — against an `asset-manager` older than the
-   * 2026-08-17 deploy, which never sent the field (doc 240 §4.3). An empty
+   * ⚠️ Returns `[]` — not an error — against a server older than the
+   * 2026-08-17 release, which never sent the field at all. An empty
    * array is therefore "no variants OR old server". For a plain existence
    * check prefer `hasPreset(dto, preset)` on `dto.presets`, which every server
    * version sends; use this when you need the URLs and sizes.
@@ -601,12 +634,13 @@ class AssetsApi {
    * Passing no presets re-runs the FULL default pipeline for that
    * asset's kind (thumb+sm+md+lg for images, poster+video for video).
    *
-   * If the asset was uploaded original-only and the cleanup job has
-   * already reaped `raw/`, the route falls back to reading the source
-   * bytes from `variants/o.<ext>` — no need to re-upload.
+   * If the asset was uploaded original-only and the ~24 h grace window
+   * on the uploaded bytes has already closed, the route falls back to
+   * 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 the Cloud Run Job (the call returns immediately
+   * dispatched to a background job (the call returns immediately
    * with a dispatch handle; poll `aq.assets.get(id).status` for
    * completion).
    */
@@ -642,13 +676,13 @@ class AssetsApi {
   }
 
   /**
-   * Request a presigned R2 PUT URL for direct browser-side uploads.
+   * Request a presigned storage PUT URL for direct browser-side uploads.
    *
    * Mirrors the first half of `aq.upload()` — the caller (typically a
    * BFF / share-link dropzone) computes sha256 in the browser, then
-   * uploads bytes straight to R2 with the returned `upload.url`, then
-   * POSTs `process.body` to `/assets/process` (see {@link processAndWait})
-   * once R2 has the bytes.
+   * uploads bytes straight to object storage with the returned `upload.url`,
+   * then POSTs `process.body` to `/assets/process` (see {@link processAndWait})
+   * once storage has the bytes.
    *
    * If the sha is already known to the tenant the server short-circuits
    * with `{ deduped: true, asset }` — no PUT needed.
@@ -660,16 +694,16 @@ class AssetsApi {
    * if (presign.deduped) return presign.asset;      // those bytes already exist; none fly
    *
    * // BROWSER: PUT straight to presign.upload.url — the bytes never touch your server.
-   * // ⚠️ R2 answers that preflight ITSELF, so your origin must be in the BUCKET's CORS policy.
-   * //    Symptom when it is not: "PUT failed: network error" with every earlier step green —
-   * //    and it cannot be fixed in this SDK, in your app, or in `storefront_origins`.
+   * // ⚠️ The STORAGE BUCKET answers that preflight itself, so your origin must be in its CORS
+   * //    policy. Symptom when it is not: "PUT failed: network error" with every earlier step
+   * //    green — and it cannot be fixed in this SDK, in your app, or by the API's allowed origins.
    *
    * // SERVER again, forwarding presign.process.body VERBATIM:
    * const asset = await aq.assets.processAndWait(presign.process.body, { timeoutMs: 300_000 });
    * ```
    *
    * Works for images AND video. A video answers immediately with
-   * `{ assetId, status: "processing" }` while a Cloud Run Job transcodes, so
+   * `{ assetId, status: "processing" }` while a background job transcodes, so
    * give `processAndWait` a bigger `timeoutMs` (a transcode + HLS ladder runs
    * 1–2 min; 300_000 is a sane floor).
    */
@@ -701,7 +735,7 @@ class AssetsApi {
    * {@link presignUploadUrl} call, then poll until the asset transitions
    * to `ready` or `failed`. Throws on `failed` or timeout.
    *
-   * Use this when bytes were uploaded directly from the browser to R2 —
+   * Use this when bytes were uploaded directly from the browser to storage —
    * `aq.upload()` already does presign + PUT + process + wait in one
    * step when the server holds the bytes.
    */
@@ -755,7 +789,7 @@ class AssetsApi {
    * {@link waitReady} (typical timeout: 10 min for multi-segment kits).
    *
    * Tenant scope is inherited from the SDK client; `tenantCode` is added
-   * to the request body so the Cloud Run Job can resolve it without
+   * to the request body so the background job can resolve it without
    * re-reading the header.
    */
   async composeMarketing(
@@ -858,7 +892,7 @@ export type UploadOptions = {
    * MIME type of the bytes. **Only needed for a `Uint8Array` input** — a `File`/`Blob`
    * already carries its `.type`. Raw bytes have no inherent MIME, so without this (and
    * without an extension on `fileName` to infer from) they upload as
-   * `application/octet-stream`, which the asset-manager classifies as `kind:"other"` —
+   * `application/octet-stream`, which the server classifies as `kind:"other"` —
    * meaning NO image/video variants are generated and `regenerate()` is unsupported.
    * Resolution order for the effective MIME: `Blob.type` → `contentType` →
    * inferred from `fileName`'s extension → `application/octet-stream`.
@@ -916,8 +950,8 @@ export type UploadOptions = {
   /**
    * 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
-   * videos / HLS transcodes — aquienpz processing time scales with input
-   * size and per-instance CPU.
+   * videos / HLS transcodes — processing time scales with input size,
+   * and with how much other work the platform is doing at that moment.
    *
    * Throws `Error("waitReady timeout for <id>")` if the deadline passes
    * without the asset transitioning. The asset row stays in aquienpz
@@ -1002,9 +1036,37 @@ export type UsageWindow = {
   admins: number;
   upscales: number;
   processes: number;
-  bytesIn: number;
+  /**
+   * Minutes of video actually TRANSCODED in the window — source minutes ×
+   * encode passes, so a 7-rung HLS ladder over a 2-minute clip books 14.
+   *
+   * A re-encode of a video already ingested counts AGAIN. That is the point:
+   * an asset count cannot report it, because re-encoding an asset that already
+   * exists creates no new asset.
+   *
+   * A stream copy (`video: { passthrough: true }`, or an idempotent cache skip)
+   * books nothing, so a tenant that ran no encoder reads `0` — and that `0` is real.
+   */
+  videoMinutes: number;
+  /** Encode passes behind `videoMinutes`. 0 when nothing was encoded. */
+  videoEncodes: number;
 };
 
+/**
+ * ⚠️ REMOVED 2026-08-17: `bytesIn` on `UsageWindow`/`UsageDailyPoint` and
+ * `bytesTotal` on `UsagePerKey`.
+ *
+ * All three were structurally zero: the field behind them was never populated,
+ * on any row. They could not be instrumented in place either — uploads go to
+ * object storage through presigned URLs, so the payload never passes through
+ * the API, and the only figure measurable there is a JSON envelope of a few
+ * hundred bytes.
+ *
+ * A field that always reads `0` is worse than an absent field, because absent
+ * is honest — a `0` next to a real `storage.totalBytes` reads as a measurement.
+ * The byte number that IS true is still served: `storage.totalBytes`.
+ */
+
 export type UsageDailyPoint = {
   date: string;
   reads: number;
@@ -1012,8 +1074,10 @@ export type UsageDailyPoint = {
   lists: number;
   deletes: number;
   processes: number;
-  bytesIn: number;
   bytesStored: number;
+  /** See `UsageWindow.videoMinutes`. Minutes transcoded on this day. */
+  videoMinutes: number;
+  videoEncodes: number;
 };
 
 export type UsagePerKey = {
@@ -1021,7 +1085,6 @@ export type UsagePerKey = {
   prefix: string | null;
   name: string | null;
   opsTotal: number;
-  bytesTotal: number;
   lastSeen: string;
 };
 
@@ -1136,7 +1199,7 @@ export class NitidaClient {
    * Returns the canonical `lg` variant URL when called with empty options,
    * so callers can swap `urlFor()` for `transform()` without thinking.
    *
-   * URLs with the same params in different order produce the same R2
+   * URLs with the same params in different order produce the same
    * cache entry (the server canonicalizes both sides). Safe to use as
    * stable cache keys.
    *
@@ -1236,12 +1299,12 @@ export class NitidaClient {
    * Build an on-the-fly VIDEO transform URL — Phase 4.
    *
    * Same DSL shape as `transform()` but the URL has a `.mp4` (default)
-   * or `.webm` extension and the server routes the request to a Cloud
-   * Run Job for ffmpeg encoding (vs the inline sharp pipeline for
+   * or `.webm` extension and the server routes the request to a
+   * background job for video encoding (vs the inline pipeline for
    * images).
    *
    * On the first request the route returns **202 Accepted** with
-   * `Retry-After: 10` while the Job runs (typically 5-30 s for a
+   * `Retry-After: 10` while the encode runs (typically 5-30 s for a
    * short clip). The response body includes `outputUrl` which is the
    * eventual CDN URL — poll the same transform URL after the
    * retry-after window to get a 302 redirect to it.
@@ -1283,7 +1346,7 @@ export class NitidaClient {
    *   />
    *
    * On the first request the server returns **202 Accepted** while a
-   * Cloud Run Job builds the multi-rung ladder (typically 1-3 min for
+   * background job builds the multi-rung ladder (typically 1-3 min for
    * a 90 s source — five rungs of 240p/360p/480p/720p/1080p @ AAC).
    * Subsequent requests hit the cache → **302** to the master.m3u8.
    *
@@ -1308,13 +1371,13 @@ export class NitidaClient {
    * but isn't always available depending on the runtime).
    */
   /**
-   * Upload bytes end to end: optional client compression → sha256 → presign → **direct-to-R2 PUT**
+   * Upload bytes end to end: optional client compression → sha256 → presign → **direct-to-storage PUT**
    * → `/assets/process` → wait until the asset is ready.
    *
    * ⚠️ `presets` decides what exists FOREVER. Omit it and only `original` is written; ask for
    * `["thumb"]` and the bytes you just uploaded are **not retrievable**. A variant not requested in
-   * this first ingest cannot be added later once the cleanup job reaps `raw/` — measured once as
-   * "97 files archived successfully, zero recoverable".
+   * this first ingest cannot be added later once the ~24 h grace window on the uploaded bytes
+   * closes — measured once as "97 files archived successfully, zero recoverable".
    *
    * @example Deliver an image on a site (the responsive ladder)
    * ```ts
@@ -1345,11 +1408,11 @@ export class NitidaClient {
    * @example Video — and what does NOT work there
    * ```ts
    * // `original` is accepted and then silently DROPPED: /assets/process filters video presets to
-   * // {poster, video, aiproxy, probe} before dispatching the transcode Job.
+   * // {poster, video, aiproxy, probe} before dispatching the background transcode.
    * await aq.upload(clip, { fileName: "tour.mp4", presets: ["poster", "video"] });
    *
-   * // Omit `aiproxy`/`probe` unless the asset really goes to a vision model — they cost Job time
-   * // and permanent R2 objects that nothing else reads.
+   * // Omit `aiproxy`/`probe` unless the asset really goes to a vision model — they cost encode
+   * // time and permanent stored objects that nothing else reads.
    * ```
    */
   async upload(
@@ -1360,7 +1423,7 @@ export class NitidaClient {
     //    "should we compress this?")
     const sourceIsBlob = input instanceof File || input instanceof Blob;
     // A Uint8Array has no inherent MIME. Fall back to an explicit `contentType`, then to
-    // the file extension, before octet-stream (which the asset-manager files as
+    // the file extension, before octet-stream (which the server files as
     // `kind:"other"` — no variants). A File/Blob's own `.type` always wins when present.
     const sourceMime =
       (sourceIsBlob ? input.type : "") ||
@@ -1494,7 +1557,7 @@ export class NitidaClient {
       body: new Blob([bytes as unknown as ArrayBuffer], { type: mime }),
     });
     if (!putR.ok)
-      throw new Error(`R2 PUT ${putR.status}: ${await putR.text()}`);
+      throw new Error(`Storage PUT ${putR.status}: ${await putR.text()}`);
 
     const procR = await fetch(endpointHref(this.opts, presign.process.url), {
       method: "POST",

package/src/server/index.ts

@@ -10,9 +10,9 @@
  *   import { NitidaClient } from "@nitida/sdk/server";
  *
  *   const aq = new NitidaClient({
- *     endpoint:   process.env.ASSET_MANAGER_URL!,
- *     apiKey:     process.env.ASSET_MANAGER_API_KEY!,   // <- required
- *     tenantCode: "realtyone-cr",
+ *     endpoint:   process.env.AQUIENPZ_URL!,
+ *     apiKey:     process.env.AQUIENPZ_API_KEY!,   // <- required
+ *     tenantCode: "acme-co",
  *     tenantId:   1,
  *     // signingKey: optional, only for `aq.transform(..., { sign: true })`
  *   });
@@ -32,9 +32,11 @@
  *     globally; File-API workflows are documented on the /web subpath instead)
  *
  * What's NOT here (use `@nitida/sdk/web` instead):
- *   - `createWebUploader` (multipart UploadTask with IndexedDB resume)
  *   - `compressImage` (browser-side compressorjs + heic2any)
  *
+ * And what exists nowhere: there is no `createWebUploader`. Multipart is not
+ * exposed from any subpath — `aq.upload()` is the supported path.
+ *
  * Stripe/Cloudinary historically shipped two separate packages
  * (`stripe` vs `@stripe/stripe-js`, `cloudinary` vs `@cloudinary/url-gen`)
  * for this split. Modern providers (Vercel Blob, Uploadthing, Better
@@ -51,9 +53,9 @@ import { NitidaClient as BaseNitidaClient, type NitidaClientOptions } from "..";
  * Cloud Run, Vercel Functions, edge runtimes, BFFs).
  *
  *   const aq = new NitidaClient({
- *     endpoint:   process.env.ASSET_MANAGER_URL!,
- *     apiKey:     process.env.ASSET_MANAGER_API_KEY!,
- *     tenantCode: "realtyone-cr",
+ *     endpoint:   process.env.AQUIENPZ_URL!,
+ *     apiKey:     process.env.AQUIENPZ_API_KEY!,
+ *     tenantCode: "acme-co",
  *     tenantId:   1,
  *   });
  */

package/src/web/index.ts

@@ -13,7 +13,7 @@
  *     // Point at your BFF route — the SDK calls
  *     // `${endpoint}/assets/by-hash/...`, `${endpoint}/slots/...`, etc.
  *     endpoint:   "/api/am",          // relative ⇒ same-origin proxy
- *     tenantCode: "realtyone-cr",
+ *     tenantCode: "acme-co",
  *     tenantId:   1,
  *     // NO apiKey — the type strips it. Your BFF injects the bearer.
  *   });
@@ -28,7 +28,7 @@
  *     return fetch(url, {
  *       headers: {
  *         Authorization: `Bearer ${process.env.AQUIENPZ_API_KEY!}`,
- *         "X-Tenant-Code": "realtyone-cr",
+ *         "X-Tenant-Code": "acme-co",
  *       },
  *     });
  *   }
@@ -64,7 +64,7 @@ import { NitidaClient as BaseNitidaClient, type NitidaClientOptions } from "..";
  *
  *   const aq = new NitidaClient({
  *     endpoint:   "/api/am",          // OK: relative → same-origin BFF
- *     tenantCode: "realtyone-cr",
+ *     tenantCode: "acme-co",
  *     tenantId:   1,
  *     // apiKey:  "amk_rt_...",       // ERROR: TS error: not assignable
  *   });
@@ -150,9 +150,9 @@ export {
 // ---------------------------------------------------------------------------
 //
 // Wraps `@nitida/asset-compressor-web` with the SDK's
-// `DEFAULT_COMPRESSION_OPTIONS` — values derived from the realtyone-cr
-// webapp's production tuning (LISTING_STANDARD_*: quality 0.80, max-edge
-// 3840px, WebP output, 5MB PNG→JPEG threshold, strict mode). Those defaults
+// `DEFAULT_COMPRESSION_OPTIONS` — values tuned against a production
+// photo-upload workload (quality 0.80, max-edge 3840px, WebP output,
+// 5MB PNG→JPEG threshold, strict mode). Those defaults
 // differ from `@nitida/asset-compressor-web`'s own defaults (0.85 / 2880 /
 // convertSize=0) which target a slightly different audience; SDK callers
 // get the webapp-tuned values, package-direct callers keep theirs.
@@ -184,17 +184,16 @@ export type CompressStage =
 
 /**
  * Subset of compressorjs options exposed by the SDK. Matches the
- * webapp's `DEFAULT_COMPRESSION_OPTIONS` shape from the realtyone-cr
- * production back-office uploader.
+ * `DEFAULT_COMPRESSION_OPTIONS` shape below.
  */
 export type CompressOptions = {
-  /** 0..1. Default 0.80 (`LISTING_STANDARD_IMAGE_QUALITY / 100`). */
+  /** 0..1. Default 0.80. */
   quality?: number;
-  /** Output format. Default `"image/webp"` (`DEFAULT_IMAGE_TARGET_FORMAT`). */
+  /** Output format. Default `"image/webp"`. */
   mimeType?: "image/jpeg" | "image/webp";
-  /** Max edge in pixels. Default 3840 (`LISTING_STANDARD_IMAGE_WIDTH`). */
+  /** Max edge in pixels. Default 3840. */
   maxWidth?: number;
-  /** Default 3840 (`LISTING_STANDARD_IMAGE_HEIGHT`). */
+  /** Max edge in pixels. Default 3840. */
   maxHeight?: number;
   /**
    * compressorjs `convertSize`: PNG > this byte count auto-converts to
@@ -215,9 +214,9 @@ export type CompressOptions = {
 };
 
 /**
- * Webapp-tuned defaults (LISTING_STANDARD_*). These intentionally differ
- * from `@nitida/asset-compressor-web`'s package-level defaults — the
- * SDK overrides at call time.
+ * Defaults tuned against a production photo-upload workload. These
+ * intentionally differ from `@nitida/asset-compressor-web`'s
+ * package-level defaults — the SDK overrides at call time.
  */
 export const DEFAULT_COMPRESSION_OPTIONS: Required<
   Omit<CompressOptions, "keepOriginalDimensions" | "convertHeic" | "onProgress">
@@ -274,8 +273,8 @@ export async function compressImage(
   // String indirection defeats bundler static-analysis of dynamic
   // imports — Turbopack/webpack will leave this for the runtime to
   // resolve instead of failing the build when the optional peer dep
-  // isn't installed. See feedback_bun_compile_dynamic_imports (same
-  // trick used in reverse to opt OUT of bundling).
+  // isn't installed. (The same trick is used in reverse elsewhere in
+  // this SDK to opt OUT of bundling.)
   const compressorPkg = "@nitida/asset-compressor-web";
   const { compressImage: doCompress } = (await import(
     /* @vite-ignore */ /* webpackIgnore: true */ compressorPkg