@nitida/asset-client 0.14.2

package/src/slots.ts

@@ -0,0 +1,217 @@
+/**
+ * @nitida/asset-client/slots — slot resolver for tenant-named assets.
+ *
+ * Slots give tenants a way to attach stable, human-readable names
+ * ("webapp.wizard.pool-type.icon-1", "storefront.cr.hero-video.landscape_hd_16x9.mp4")
+ * to assets they uploaded. Consumers resolve names → AssetDTOs at
+ * build / runtime so their source never hardcodes a CDN URL; the
+ * admin rebinds a slot from `asset-lab-web` and every consumer picks
+ * up the swap on cache refresh.
+ *
+ * Two layers in this package:
+ *   - `resolveSlot` / `resolveSlots` — universal (server, edge,
+ *     workers) fetch helpers. Cache 60s by default.
+ *   - React hooks live in `@nitida/asset-client/react/use-slot`
+ *     (kept out of this module so the SSR-safe core stays
+ *     dependency-free of react).
+ */
+
+import type { AssetDTO, VariantPreset } from "./index";
+import { getAssetUrl, hasPreset } from "./index";
+
+// ---------------------------------------------------------------------------
+// Wire shape — matches `apps/asset-manager/src/features/assets/slots.routes.ts`
+// ---------------------------------------------------------------------------
+
+export type SlotDTO = {
+  slotKey: string;
+  /** Preset hint set when the slot was bound (e.g. `thumb` for icon slots). */
+  preset: VariantPreset | null;
+  description: string | null;
+  updatedAt: string;
+  asset: AssetDTO;
+};
+
+export type SlotResolution = {
+  /** The resolved DTO (`null` when the slot is unbound or asset missing). */
+  slot: SlotDTO | null;
+  /**
+   * Effective preset — what `url` below was built with. Resolution order:
+   *   1. caller's `preset` override
+   *   2. slot's `preset` hint
+   *   3. `lg` for images, `video` for video kind
+   */
+  preset: VariantPreset;
+  /** The CDN URL the consumer should use. */
+  url: string | null;
+};
+
+// ---------------------------------------------------------------------------
+// Config
+// ---------------------------------------------------------------------------
+
+const DEFAULT_TTL_MS = 60_000;
+const cache = new Map<string, { fetchedAt: number; value: SlotDTO | null }>();
+
+let endpoint = "https://aquienpz-asset-manager-nlchzy26qa-uc.a.run.app";
+let apiKey: string | null = null;
+let tenantCode: string | null = null;
+
+/**
+ * Configure the resolver process-wide. Call once at boot from your
+ * storefront layout / server entry / worker init.
+ *
+ *   configureSlotResolver({
+ *     endpoint: process.env.AQUIENPZ_URL,
+ *     apiKey:   process.env.ASSET_MANAGER_RUNTIME_KEY,
+ *     tenantCode: "realtyone-cr",
+ *   });
+ */
+export function configureSlotResolver(opts: {
+  endpoint?: string;
+  apiKey?: string;
+  tenantCode?: string;
+}): void {
+  if (opts.endpoint) endpoint = opts.endpoint.replace(/\/+$/, "");
+  if (opts.apiKey !== undefined) apiKey = opts.apiKey;
+  if (opts.tenantCode !== undefined) tenantCode = opts.tenantCode;
+}
+
+/** Wipe the in-process cache (test helper or forced refresh). */
+export function invalidateSlotCache(slotKey?: string): void {
+  if (slotKey === undefined) cache.clear();
+  else
+    for (const k of cache.keys())
+      if (k.endsWith(`:${slotKey}`)) cache.delete(k);
+}
+
+// ---------------------------------------------------------------------------
+// Internal fetch helper
+// ---------------------------------------------------------------------------
+
+const baseHeaders = (): Record<string, string> => {
+  const h: Record<string, string> = {};
+  if (apiKey) h.Authorization = `Bearer ${apiKey}`;
+  if (tenantCode) h["X-Tenant-Code"] = tenantCode;
+  return h;
+};
+
+async function fetchSlot(slotKey: string): Promise<SlotDTO | null> {
+  const r = await fetch(`${endpoint}/slots/${encodeURIComponent(slotKey)}`, {
+    headers: baseHeaders(),
+  });
+  if (r.status === 404) return null;
+  if (!r.ok) throw new Error(`slot fetch ${r.status}: ${await r.text()}`);
+  return (await r.json()) as SlotDTO;
+}
+
+async function fetchSlotsBulk(
+  slotKeys: string[],
+): Promise<Record<string, SlotDTO | null>> {
+  if (slotKeys.length === 0) return {};
+  const r = await fetch(`${endpoint}/slots/resolve`, {
+    method: "POST",
+    headers: { ...baseHeaders(), "Content-Type": "application/json" },
+    body: JSON.stringify({ keys: slotKeys }),
+  });
+  if (!r.ok) throw new Error(`slots resolve ${r.status}: ${await r.text()}`);
+  const body = (await r.json()) as { resolved: Record<string, SlotDTO | null> };
+  return body.resolved;
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export type ResolveSlotOptions = {
+  /** Override preset (caller knows the use case better than the slot binding). */
+  preset?: VariantPreset;
+  /** TTL for the in-process cache. Default 60s. Set 0 to bypass. */
+  ttlMs?: number;
+};
+
+/**
+ * Resolve a single slot to a CDN URL. Returns `{slot: null, url: null}`
+ * when the slot is unbound — callers fall back to a placeholder.
+ *
+ * Cached for `ttlMs` (default 60s). Slot rebindings propagate within the
+ * TTL window without an app restart.
+ */
+export async function resolveSlot(
+  slotKey: string,
+  opts: ResolveSlotOptions = {},
+): Promise<SlotResolution> {
+  const ttl = opts.ttlMs ?? DEFAULT_TTL_MS;
+  const cacheKey = `${tenantCode ?? "_"}:${slotKey}`;
+  const now = Date.now();
+  let dto: SlotDTO | null;
+  const hit = cache.get(cacheKey);
+  if (hit && now - hit.fetchedAt < ttl) {
+    dto = hit.value;
+  } else {
+    dto = await fetchSlot(slotKey);
+    cache.set(cacheKey, { fetchedAt: now, value: dto });
+  }
+  return materializeResolution(dto, opts.preset);
+}
+
+/**
+ * Bulk-resolve N slot keys in one round-trip. The SDK's `useSlots`
+ * React hook calls this so every storefront header (logo + tagline +
+ * nav cover + …) loads as one request.
+ */
+export async function resolveSlots(
+  slotKeys: string[],
+  opts: ResolveSlotOptions = {},
+): Promise<Record<string, SlotResolution>> {
+  if (slotKeys.length === 0) return {};
+  const ttl = opts.ttlMs ?? DEFAULT_TTL_MS;
+  const now = Date.now();
+  const missing: string[] = [];
+  const out: Record<string, SlotResolution> = {};
+  for (const k of slotKeys) {
+    const cacheKey = `${tenantCode ?? "_"}:${k}`;
+    const hit = cache.get(cacheKey);
+    if (hit && now - hit.fetchedAt < ttl) {
+      out[k] = materializeResolution(hit.value, opts.preset);
+    } else {
+      missing.push(k);
+    }
+  }
+  if (missing.length > 0) {
+    const resolved = await fetchSlotsBulk(missing);
+    for (const k of missing) {
+      const dto = resolved[k] ?? null;
+      cache.set(`${tenantCode ?? "_"}:${k}`, { fetchedAt: now, value: dto });
+      out[k] = materializeResolution(dto, opts.preset);
+    }
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function defaultPresetFor(asset: AssetDTO | undefined): VariantPreset {
+  if (!asset) return "lg";
+  return asset.kind === "video" ? "video" : "lg";
+}
+
+function materializeResolution(
+  dto: SlotDTO | null,
+  overridePreset?: VariantPreset,
+): SlotResolution {
+  if (!dto) return { slot: null, preset: overridePreset ?? "lg", url: null };
+  const effective = overridePreset ?? dto.preset ?? defaultPresetFor(dto.asset);
+  // Fall back to "lg" when the bound preset doesn't exist on the asset
+  // (e.g. slot was bound to a video but caller asked for a thumb).
+  const finalPreset = hasPreset(dto.asset, effective)
+    ? effective
+    : defaultPresetFor(dto.asset);
+  return {
+    slot: dto,
+    preset: finalPreset,
+    url: getAssetUrl(dto.asset, finalPreset),
+  };
+}

package/src/transform.ts

@@ -0,0 +1,410 @@
+/**
+ * On-the-fly transform URL builder.
+ *
+ * Mirrors the server's DSL canonicalizer byte-for-byte so a URL generated
+ * here hashes to the same R2 cache key as the server's canonical form.
+ *
+ * Canonicalization rules (keep in sync with
+ * `apps/asset-manager/src/features/assets/transform.dsl.ts`):
+ *   - Drop entries whose value is `undefined`
+ *   - Sort keys alphabetically
+ *   - Numbers rendered without leading zeros or trailing dots
+ *   - String values lowercased
+ *
+ * URL shape:
+ *   <cdnBase>/t/<dsl>/<sha>.<ext>
+ *
+ * The `.ext` is informational (browser content-sniff hint); the server
+ * decides the actual output format from the DSL `format` param + the
+ * request's Accept header.
+ */
+
+import type { AssetDTO } from "./index";
+import { getCdnBase } from "./index";
+
+/**
+ * Widths the CDN edge whitelists (DoS guard — see `apps/cdn-proxy` WHITELIST_WIDTHS).
+ * Requesting any OTHER width returns HTTP 400 at the edge (unsigned URLs). These are the
+ * 1× base ladder values; DPR ×2/×3 multiples are applied + whitelisted server-side. Import
+ * this instead of hardcoding magic widths so an unsupported size is caught in review/IDE.
+ */
+export const TRANSFORM_WIDTHS = [
+  96, 128, 160, 240, 256, 320, 400, 480, 600, 640, 800, 960, 1080, 1200, 1280,
+  1440, 1600, 1920, 2560, 3840,
+] as const;
+/**
+ * A CDN-whitelisted transform width — the only widths `TransformOptions.width`
+ * accepts. Off-ladder widths are a compile error; for signed URLs that need a
+ * custom width, use {@link SignedTransformOptions} (number) via
+ * {@link getSignedTransformUrl} / `aq.transform(asset, opts, { sign: true })`.
+ */
+export type TransformWidth = (typeof TRANSFORM_WIDTHS)[number];
+
+export type TransformFit = "cover" | "contain" | "fill" | "inside" | "outside";
+export type TransformGravity =
+  | "auto"
+  | "face"
+  | "center"
+  | "north"
+  | "south"
+  | "east"
+  | "west";
+export type TransformFormat =
+  | "auto"
+  | "avif"
+  | "webp"
+  | "jpeg"
+  | "png"
+  // Video-only formats (Phase 4). The image path ignores them.
+  | "mp4"
+  | "webm"
+  // HLS adaptive ladder (Phase 5). Video-only. Output is a directory
+  // of m3u8 + .ts segments fronted by master.m3u8; the SDK returns
+  // the master URL via `getHlsStreamingUrl`.
+  | "hls";
+export type TransformEffect = "removebg" | "genfill";
+
+export type TransformOptions = {
+  /**
+   * Target max-side width in CSS pixels (multiplied by `dpr` server-side).
+   * MUST be a {@link TRANSFORM_WIDTHS} value — off-ladder widths are rejected
+   * (HTTP 400) by the edge whitelist for unsigned URLs, so the type forbids
+   * them at compile time. For SIGNED URLs with a custom width, use
+   * {@link SignedTransformOptions} (which widens this to `number`).
+   */
+  width?: TransformWidth;
+  /** Target max-side height. Multiplied by `dpr` server-side. */
+  height?: number;
+  /** Resize fit mode. Default `cover` server-side. */
+  fit?: TransformFit;
+  /** Crop gravity. `auto` uses sharp's `attention` strategy. */
+  gravity?: TransformGravity;
+  /** Output format. `auto` → policy decides (see asset-manager bench). */
+  format?: TransformFormat;
+  /** Output quality. `auto` → format-specific default. */
+  quality?: "auto" | number;
+  /** Device pixel ratio. Width/height are multiplied by this before resize. */
+  dpr?: 1 | 2 | 3;
+  /**
+   * AI effect applied before resize/encode.
+   *
+   *   - `removebg`: remove the background; output is a transparent PNG
+   *     of the foreground subject. Forces `format=png` regardless of
+   *     other format hints. Runs U²-Net ONNX locally (or BRIA via
+   *     Replicate when `BG_REMOVAL_BACKEND=replicate`). Single cache
+   *     miss per (sha, dsl) tuple; subsequent identical DSLs serve
+   *     from R2 — no inference, no per-image cost.
+   *
+   *   - `genfill`: aspect-extension outpaint via Flux-Fill Pro on
+   *     Replicate. Requires BOTH `width` and `height` — the server
+   *     fits the source centered into the target canvas and outpaints
+   *     the gutters. Output is PNG (forced) at exactly target dims.
+   *     ~$0.05/image first time; same R2 cache as removebg after.
+   *     Primary use case: building OG cards (1200×630) from portrait
+   *     listing photos without awkward edge mirroring.
+   */
+  effect?: TransformEffect;
+  /**
+   * Video-only: clip start in seconds. Image transforms ignore.
+   * Accepts decimals (e.g. 1.5 for sub-second seek).
+   */
+  start?: number;
+  /**
+   * Video-only: clip duration in seconds (1..300). Image transforms
+   * ignore. With `start`, lets a single request grab a sub-clip.
+   */
+  duration?: number;
+};
+
+/**
+ * Like {@link TransformOptions} but with `width` widened to any `number` —
+ * the escape hatch for SIGNED URLs that need an off-ladder custom width.
+ *
+ * The edge whitelist only rejects off-ladder widths on UNSIGNED URLs; a valid
+ * `?sig=` earns the whitelist bypass at the worker (the asset-manager still
+ * does the real HMAC check). So a custom width is ONLY safe when the URL is
+ * signed — hence this type is accepted exclusively by the signing helpers
+ * ({@link getSignedTransformUrl} / `aq.transform(asset, opts, { sign: true })`),
+ * never by the plain unsigned {@link getTransformUrl}.
+ */
+export type SignedTransformOptions = Omit<TransformOptions, "width"> & {
+  /** Off-ladder width — valid ONLY on signed URLs (edge whitelist bypass). */
+  width?: number;
+};
+
+/**
+ * Serialize transform options into the canonical DSL path segment.
+ * Empty options return an empty string (caller should fall back to a
+ * variant URL instead of a transform URL in that case).
+ *
+ * Accepts {@link SignedTransformOptions} (the wider type) so it also covers
+ * custom-width signed URLs; {@link TransformOptions} is assignable to it.
+ */
+/**
+ * Extract the 16-hex short sha from an aquienpz CDN URL, regardless of
+ * shape:
+ *   - tenant-prefixed variant:  `https://8ok.uk/4/v/<sha16>-<preset>.<ext>`
+ *   - legacy variant:           `https://8ok.uk/<sha16>-<preset>.<ext>`
+ *   - on-the-fly transform:     `https://8ok.uk/t/<dsl>/<sha16>.<ext>`
+ *   - streaming HLS:            `https://8ok.uk/t/format=hls/<sha16>.m3u8`
+ *
+ * Returns `null` for non-aquienpz URLs (pexels, googleusercontent, raw
+ * uploaded URLs to other CDNs) so call sites can fall back to the URL
+ * with a plain `<img>` instead of generating a broken transform URL.
+ *
+ * Useful when a value reaches the component as a pre-built URL string
+ * (legacy data, site-config JSON, third-party feeds) but you want to
+ * drop in `getTransformSrcSet` for the responsive ladder if it happens
+ * to be an aquienpz asset.
+ */
+export function extractAssetSha(url: string | null | undefined): string | null {
+  if (!url) return null;
+  // Match the canonical aquienpz sha pattern: 16 lowercase hex chars
+  // appearing as a path segment, optionally followed by `-<preset>`
+  // (variant URL) or `.<ext>` (transform URL).
+  const m = url.match(/\/([0-9a-f]{16})(?:[-.]|$)/);
+  return m ? m[1]! : null;
+}
+
+export function serializeTransform(opts: SignedTransformOptions): string {
+  const entries: Array<[string, string]> = [];
+  const keys = Object.keys(opts).sort() as Array<keyof SignedTransformOptions>;
+  for (const k of keys) {
+    const v = opts[k];
+    if (v == null) continue;
+    const serialized = typeof v === "string" ? v.toLowerCase() : String(v);
+    entries.push([k, serialized]);
+  }
+  return entries.map(([k, v]) => `${k}=${v}`).join(",");
+}
+
+function extForOptions(opts: SignedTransformOptions): string {
+  // effect=removebg forces PNG output server-side (needs alpha).
+  if (opts.effect === "removebg") return "png";
+  // effect=genfill defaults to WebP (12× lighter than the raw Flux-Fill
+  // PNG output with no visible loss at q=85). Explicit `format=png`
+  // opts back into lossless for print / marketing fold-outs. The server
+  // re-encodes Flux's PNG → target format before R2 cache.
+  if (opts.effect === "genfill") {
+    switch (opts.format) {
+      case "png":
+        return "png";
+      case "avif":
+        return "avif";
+      case "jpeg":
+        return "jpg";
+      default:
+        return "webp";
+    }
+  }
+  switch (opts.format) {
+    case "avif":
+      return "avif";
+    case "jpeg":
+      return "jpg";
+    case "png":
+      return "png";
+    case "mp4":
+      return "mp4";
+    case "webm":
+      return "webm";
+    case "hls":
+      // HLS uses `.m3u8` as the URL extension; the route resolves the
+      // master playlist under the cache key prefix.
+      return "m3u8";
+    default:
+      // "webp" / "auto" / undefined / anything new
+      return "webp";
+  }
+}
+
+/**
+ * Build a transform URL for a VIDEO asset. Same DSL shape as image
+ * transforms; the server branches on the asset's `kind` column. Video
+ * URLs use `.mp4` (default) or `.webm` extension and on cache miss the
+ * server returns 202 Accepted while a Cloud Run Job encodes the clip;
+ * subsequent GETs return 302 to the cached R2 object.
+ *
+ *   <video src={aq.transformVideo(asset, { width: 1080, height: 1920 })}
+ *          autoPlay muted loop playsInline />
+ */
+export function getVideoTransformUrl(
+  asset: Pick<AssetDTO, "sha">,
+  opts: TransformOptions,
+): string | null {
+  const dsl = serializeTransform(opts);
+  if (!dsl) return null;
+  const ext = opts.format === "webm" ? "webm" : "mp4";
+  return `${getCdnBase()}/t/${dsl}/${asset.sha}.${ext}`;
+}
+
+/**
+ * Build an HLS streaming URL for a VIDEO asset (Phase 5). Returns the
+ * master.m3u8 entry point — HLS-aware players (Video.js's
+ * @videojs/http-streaming, hls.js, native iOS Safari) follow it to
+ * fetch the variant playlist + segments at the appropriate bitrate
+ * for the connection.
+ *
+ * ⚠️ A master.m3u8 is NOT a video file. Assigning it to `<video src>`
+ * works only where the engine has native HLS; everywhere else it needs
+ * an MSE player. And the classic feature test is now WRONG: Chrome 147
+ * (April 2026) added native HLS, so `canPlayType("application/vnd.apple.mpegurl")`
+ * answers "maybe" there and routes Chrome to the native branch, where it
+ * opened a measured 17 s hero at 426x240 for ~8 s. Branch on the ENGINE:
+ *
+ * @example
+ * ```ts
+ * function prefersNativeHls(video: HTMLVideoElement): boolean {
+ *   if (video.canPlayType("application/vnd.apple.mpegurl") === "") return false;
+ *   // Apple's engine, or an engine with no MSE to fall back on (iOS < 17.1).
+ *   return "ManagedMediaSource" in globalThis || !("MediaSource" in globalThis);
+ * }
+ *
+ * const src = getHlsStreamingUrl(asset);
+ * if (prefersNativeHls(video)) {
+ *   video.src = src;
+ * } else {
+ *   // Defaults open at a fixed low rung — measure instead of guessing.
+ *   const hls = new Hls({ startLevel: -1, testBandwidth: true, abrEwmaDefaultEstimate: 1_000_000 });
+ *   hls.loadSource(src);
+ *   hls.attachMedia(video);
+ * }
+ * ```
+ *
+ * On first request the server returns 202 Accepted while a Cloud Run
+ * Job transcodes the ladder (typically 1-3 min for a 90 s source);
+ * subsequent requests get 302 to the cached master.m3u8. Keep the
+ * progressive MP4 as a fallback source for that window.
+ *
+ * The ladder's ceiling is the source the job probes: built at ingest it
+ * reads the RAW upload and a 4K master yields 1440p/2160p rungs; rebuilt
+ * on demand after the raw is unavailable it reads the `-v.mp4`, which is
+ * capped at 1920 wide. `getAssetUrl(sha, "video")` is always <= 1080p.
+ */
+export function getHlsStreamingUrl(
+  asset: Pick<AssetDTO, "sha">,
+  opts: Omit<TransformOptions, "format"> = {},
+): string {
+  // Always serialize with format=hls so the server routes correctly.
+  const merged: TransformOptions = { ...opts, format: "hls" };
+  const dsl = serializeTransform(merged);
+  return `${getCdnBase()}/t/${dsl}/${asset.sha}.m3u8`;
+}
+
+/**
+ * Build a transform URL. Returns null when the caller passed no options —
+ * callers should prefer the existing variant URL builder in that case so
+ * the request hits a pre-generated variant instead of an on-the-fly encode.
+ */
+function buildTransformUrl(
+  asset: Pick<AssetDTO, "sha">,
+  opts: SignedTransformOptions,
+): string | null {
+  const dsl = serializeTransform(opts);
+  if (!dsl) return null;
+  const ext = extForOptions(opts);
+  return `${getCdnBase()}/t/${dsl}/${asset.sha}.${ext}`;
+}
+
+export function getTransformUrl(
+  asset: Pick<AssetDTO, "sha">,
+  opts: TransformOptions,
+): string | null {
+  return buildTransformUrl(asset, opts);
+}
+
+/**
+ * Build AND sign a transform URL, allowing an off-ladder custom `width`.
+ *
+ * This is the escape hatch for {@link SignedTransformOptions}: off-ladder
+ * widths only pass the edge whitelist when the URL is signed, so building one
+ * and signing it must happen together. For on-ladder widths prefer the plain
+ * {@link getTransformUrl} (+ {@link signTransformUrl} if you need a signature).
+ *
+ * Returns `null` only when `opts` serialize to an empty DSL (no transform
+ * requested) — same contract as {@link getTransformUrl}.
+ */
+export function getSignedTransformUrl(
+  asset: Pick<AssetDTO, "sha">,
+  opts: SignedTransformOptions,
+  signingKey: string,
+): Promise<string> | null {
+  const url = buildTransformUrl(asset, opts);
+  if (!url) return null;
+  return signTransformUrl(url, signingKey);
+}
+
+/**
+ * Sign a transform URL with the tenant's HMAC signing key. Appends
+ * `?sig=<hex>` where hex = HMAC-SHA256(signingKey, `<canonical-DSL>/<filename>`).
+ *
+ * Must agree byte-for-byte with the server's `verifyTransformSignature`.
+ * Uses WebCrypto, so works in browsers, Node ≥ 16, Bun, and Workers.
+ *
+ * The canonical DSL is the one already produced by `serializeTransform`
+ * (sort keys + lowercase strings), so signing a URL built by `getTransformUrl`
+ * is automatic — the same canonical form is in the URL path.
+ */
+export async function signTransformUrl(
+  unsignedUrl: string,
+  signingKey: string,
+): Promise<string> {
+  const u = new URL(unsignedUrl);
+  // Path shape: /t/<dsl>/<filename>
+  const parts = u.pathname.split("/").filter(Boolean);
+  // First segment must be "t"; the rest is dsl groups + filename. With
+  // Phase 1 we ship a single DSL group; chained groups stay flat for
+  // signing purposes (server canonicalizer flattens them too).
+  if (parts[0] !== "t" || parts.length < 3) {
+    throw new Error(`signTransformUrl: unexpected URL shape ${unsignedUrl}`);
+  }
+  const filename = parts[parts.length - 1]!;
+  const dsl = parts.slice(1, -1).join("/");
+  const message = `${dsl}/${filename}`;
+  const sig = await hmacSha256Hex(signingKey, message);
+  u.searchParams.set("sig", sig);
+  return u.toString();
+}
+
+async function hmacSha256Hex(key: string, message: string): Promise<string> {
+  const enc = new TextEncoder();
+  const cryptoKey = await crypto.subtle.importKey(
+    "raw",
+    enc.encode(key),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"],
+  );
+  const buf = await crypto.subtle.sign("HMAC", cryptoKey, enc.encode(message));
+  return [...new Uint8Array(buf)]
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("");
+}
+
+/**
+ * Build a responsive `srcSet` string by generating one transform URL per
+ * width. All other options apply to every URL.
+ *
+ *   <img
+ *     src={aq.transform(asset, { width: 800 })!}
+ *     srcSet={aq.transformSrcSet(asset, [320, 640, 960, 1280])}
+ *     sizes="(max-width: 768px) 100vw, 50vw"
+ *   />
+ */
+export function getTransformSrcSet(
+  asset: Pick<AssetDTO, "sha">,
+  widths: number[],
+  extraOpts: Omit<TransformOptions, "width"> = {},
+): string {
+  return widths
+    .map((w) => {
+      // Build via the internal (number-width) builder: `widths` is an explicit
+      // responsive ladder the caller chose, so it stays `number[]`. Off-ladder
+      // unsigned widths 400 at the edge — the caller's responsibility, exactly
+      // as before the width type was tightened.
+      const url = buildTransformUrl(asset, { ...extraOpts, width: w });
+      return url ? `${url} ${w}w` : null;
+    })
+    .filter((s): s is string => s != null)
+    .join(", ");
+}