@stapel/cdn-react 0.1.0

package/src/index.ts

@@ -0,0 +1,154 @@
+/**
+ * `@stapel/cdn-react` — the headless React pair for stapel-cdn
+ * (frontend-standard §2). Business + state only, zero visual opinion; the antd
+ * skin lives behind the `./default` subpath, so a host that renders its own
+ * upload control carries none of it.
+ *
+ * ── The one-liner ──────────────────────────────────────────────────────────
+ *
+ * ```tsx
+ * const runtime = createCdnRuntime({ baseUrl: "/cdn/api/v1/" });
+ * <CdnProvider runtime={runtime}>
+ *   <MediaUploader max={10} onRefsChange={setImagesDraft}>
+ *     {(bag) => <YourGrid bag={bag} />}
+ *   </MediaUploader>
+ * </CdnProvider>
+ * ```
+ *
+ * ── The three properties this pair exists to guarantee ─────────────────────
+ *
+ * 1. **Dedup happens before the bytes move.** The flow hashes the file, asks
+ *    `file/exists/`, and on a hit returns the reference having sent NOTHING.
+ *    That is the property the storefront spec asks to be proven, and
+ *    `test/dedup.test.ts` proves it by counting requests. The pre-check is an
+ *    optimisation, so it is never allowed to fail the upload: a guest (401 —
+ *    the endpoint is stricter than the upload endpoints), a page with no
+ *    `crypto.subtle`, or a check that simply errors all fall through to the
+ *    POST and say so in `dedupSkipped`.
+ * 2. **The unit handed out is the reference, not a URL.** `<type>/<hash>` is
+ *    what `Profile.avatar` and `Listing.images_draft` store, and it is opaque:
+ *    the pair does not build URLs out of it and neither should a caller. The
+ *    row that comes back carries the URLs, and `toStapelImage` converts its
+ *    ladder for `@stapel/image` in the single place that knows the two
+ *    contracts spell `tier` differently.
+ * 3. **A switched-off control states its reason.** `canAdd` and `settled` are
+ *    `ActionAvailability`, so "the gallery is full", "wait for the uploads"
+ *    and "retry the ones that failed" are three different sentences rather
+ *    than one grey button.
+ *
+ * ── What this pair does NOT do ─────────────────────────────────────────────
+ *
+ * No progress percentage: `fetch` cannot observe request-body progress and
+ * `crypto.subtle` reports nothing mid-digest, so the bag names the PHASE and a
+ * skin shows an indeterminate indicator. Forking onto `XMLHttpRequest` to get
+ * a number would mean a second transport with its own auth, refresh and error
+ * handling — the exact duplication this package was extracted to end.
+ *
+ * No `refs/sync/`: that endpoint is `IsServiceRequest` and unreachable from a
+ * browser by construction. Reference bookkeeping belongs to the module that
+ * owns the entity.
+ *
+ * No public read-by-reference: `file/exists/` is owner-scoped, so `useCdnRef`
+ * resolves the CALLER's own references (a reopened draft) and cannot render a
+ * stranger's gallery. Recorded as an upstream gap in the README rather than
+ * worked around with a URL convention this pair would have invented.
+ *
+ * Layers: api → model → headless → i18n. Generated surfaces (the typed schema,
+ * the error map, the manifest, llms.txt) are produced by the monorepo `gen:*`
+ * drivers from stapel-cdn's own `docs/` artifacts and stand under drift gates.
+ */
+
+// ── api ──────────────────────────────────────────────────────────────────────
+export { createCdnApi } from "./api/cdnApi.js";
+export type { CdnApi } from "./api/cdnApi.js";
+export type {
+  CdnFileExistsResponse,
+  CdnFileKind,
+  CdnFileModel,
+  CdnFileUploadResponse,
+  CdnImage,
+  CdnImageUploadResponse,
+  CdnRef,
+  CdnVariantMeta,
+  CdnVideo,
+  CdnVideoUploadResponse,
+  ParsedCdnRef,
+  Schemas,
+} from "./api/types.js";
+
+// ── model: the flow, the mirror, the reference ───────────────────────────────
+export { createCdnRuntime } from "./model/runtime.js";
+export type { CdnRuntime, CreateCdnRuntimeOptions } from "./model/runtime.js";
+export {
+  CdnRuntimeContext,
+  useCdnAnalytics,
+  useCdnApi,
+  useCdnRuntime,
+} from "./model/context.js";
+export { cdnQueryKeys } from "./model/queryKeys.js";
+export { useCdnRef } from "./model/queries.js";
+export type { CdnRefBag } from "./model/queries.js";
+export {
+  isUploadCanceled,
+  runUpload,
+  targetAssetType,
+  UploadCanceled,
+} from "./model/upload.js";
+export type {
+  CdnUploadTarget,
+  CdnVariantWaitOptions,
+  DedupSkipReason,
+  RunUploadOptions,
+  UploadOutcome,
+  UploadPhase,
+} from "./model/upload.js";
+export {
+  acceptAttribute,
+  CDN_DEFAULT_LIMITS,
+  ERROR_FILE_TOO_LARGE,
+  ERROR_INVALID_FORMAT,
+  ERROR_NO_FILE,
+  fileExtension,
+  resolveCdnLimits,
+  validateFile,
+} from "./model/limits.js";
+export type {
+  CdnIntakeLimits,
+  CdnLimits,
+  CdnLimitsOverride,
+} from "./model/limits.js";
+export { formatCdnRef, parseCdnRef, refOf, toStapelImage } from "./model/refs.js";
+export { canHashLocally, sha256Hex } from "./model/hash.js";
+
+// ── headless ─────────────────────────────────────────────────────────────────
+export { CdnProvider } from "./headless/CdnProvider.js";
+export { ImageUpload } from "./headless/ImageUpload.js";
+export { MediaUploader } from "./headless/MediaUploader.js";
+export { useUploadImage } from "./headless/useUploadImage.js";
+export type { UploadImageBag } from "./headless/useUploadImage.js";
+export { useUploadQueue } from "./headless/useUploadQueue.js";
+export type {
+  UploadItem,
+  UploadQueueBag,
+  UseUploadQueueOptions,
+} from "./headless/useUploadQueue.js";
+export { smallestVariantUrl, useUploadPreview } from "./headless/useUploadPreview.js";
+export type { UploadPreview } from "./headless/useUploadPreview.js";
+
+// ── flows (zero-flow shim — stapel-cdn annotates none) ───────────────────────
+export { CDN_FLOWS, flowEndpoints } from "./flows/registry.js";
+export type { CdnFlowId, CdnFlowSpec, FlowEndpoint } from "./flows/registry.js";
+
+// ── i18n ─────────────────────────────────────────────────────────────────────
+export { CDN_I18N_KEYS, cdnI18nBundleEn, registerCdnI18n } from "./i18n/keys.js";
+export {
+  CDN_ERROR_CODES,
+  CDN_ERRORS,
+  cdnErrorBundleEn,
+  explainCdnError,
+} from "./i18n/errorsMap.js";
+export type {
+  CdnErrorCode,
+  CdnErrorSpec,
+  Remediation,
+} from "./i18n/errorsMap.js";

package/src/model/context.tsx

@@ -0,0 +1,25 @@
+import type { Context } from "react";
+import { createModuleContext } from "@stapel/core";
+import type { Analytics, ModuleContextKit } from "@stapel/core";
+import type { CdnApi } from "../api/cdnApi.js";
+import type { CdnRuntime } from "./runtime.js";
+
+/**
+ * The wired {@link CdnRuntime} shared through React context by
+ * `<CdnProvider>`. Hooks in `model/` and `headless/` read the singletons from
+ * here. One reviewed copy of this plumbing lives in `@stapel/core`
+ * (`createModuleContext`); this module binds it under the pair's public names.
+ */
+const kit: ModuleContextKit<CdnRuntime> = createModuleContext<CdnRuntime>("Cdn");
+
+export const CdnRuntimeContext: Context<CdnRuntime | null> = kit.RuntimeContext;
+
+export const useCdnRuntime: () => CdnRuntime = kit.useRuntime;
+
+export const useCdnApi: () => CdnApi = kit.useApi;
+
+export const useCdnAnalytics: () => Analytics | null = kit.useAnalytics;
+
+/** @internal Re-exported as `<CdnProvider>` from `headless/`. */
+export const ModuleProvider: ModuleContextKit<CdnRuntime>["Provider"] =
+  kit.Provider;

package/src/model/hash.ts

@@ -0,0 +1,67 @@
+/**
+ * SHA-256 of a file's bytes — the key the dedup pre-check is asked with.
+ *
+ * The backend computes the same digest over the same bytes
+ * (`Image.calculate_file_hash`, `hashlib.sha256(...).hexdigest()`), so the two
+ * agree by construction: 64 lowercase hex characters of the ORIGINAL upload,
+ * before any variant exists.
+ *
+ * ── Why this can be unavailable, and why that is not an error ──────────────
+ *
+ * `crypto.subtle` exists only in a SECURE CONTEXT. On `http://` (a LAN test
+ * box, an old staging host) it is simply not there, and neither is the
+ * pre-check. That is a lost optimisation, not a lost upload: the server
+ * deduplicates on its own side regardless, so the POST is still correct — it
+ * just costs the bytes. {@link canHashLocally} lets the flow say which of the
+ * two paths it took instead of failing, and `UploadItem.dedupSkipped` carries
+ * the reason all the way to a skin that wants to explain it.
+ *
+ * ── Why there is no progress here ──────────────────────────────────────────
+ *
+ * `SubtleCrypto.digest` takes the whole buffer and returns one promise; it
+ * reports nothing in between and cannot be chunked without hand-rolling
+ * SHA-256, which is not a thing to hand-roll. Hashing is therefore a PHASE
+ * with a duration, not a percentage — see `model/upload.ts` on why the whole
+ * bag is phase-shaped.
+ */
+
+/** Whether this context can compute the digest at all (see the header). */
+export function canHashLocally(): boolean {
+  return (
+    typeof globalThis.crypto !== "undefined" &&
+    typeof globalThis.crypto.subtle?.digest === "function"
+  );
+}
+
+function toHex(buffer: ArrayBuffer): string {
+  const bytes = new Uint8Array(buffer);
+  let out = "";
+  for (const byte of bytes) out += byte.toString(16).padStart(2, "0");
+  return out;
+}
+
+/**
+ * `digest` is handed a `Uint8Array` VIEW rather than the raw `ArrayBuffer`.
+ * Both are valid `BufferSource`, but a buffer that crossed a realm boundary
+ * fails a strict `instanceof ArrayBuffer` check in some implementations (jsdom
+ * is one, which is where this surfaced), while a typed-array view is accepted
+ * everywhere. The view costs nothing — no copy — and removes a portability
+ * hazard that would otherwise only show up in somebody else's environment.
+ */
+const bufferSource = (buffer: ArrayBuffer): Uint8Array<ArrayBuffer> =>
+  new Uint8Array(buffer);
+
+/**
+ * The 64-character lowercase hex SHA-256 of `blob`'s bytes.
+ *
+ * Throws whatever the platform throws when there is no `crypto.subtle` — call
+ * {@link canHashLocally} first; the upload flow does.
+ */
+export async function sha256Hex(blob: Blob): Promise<string> {
+  const buffer = await blob.arrayBuffer();
+  const digest = await globalThis.crypto.subtle.digest(
+    "SHA-256",
+    bufferSource(buffer)
+  );
+  return toHex(digest);
+}

package/src/model/limits.ts

@@ -0,0 +1,207 @@
+/**
+ * The client-side mirror of stapel-cdn's own intake gates.
+ *
+ * ── Why mirror at all ──────────────────────────────────────────────────────
+ *
+ * Because the alternative is uploading 40 MB over a phone connection to be
+ * told "File is too large" by the server that just received all of it. The
+ * gates below are the cheap half of what `_validate_image_upload` does before
+ * it hashes a byte (`stapel_cdn/views.py`): the size ceiling and the extension
+ * allowlist. The expensive half — an actual libvips decode, which is what
+ * catches a `.jpg` full of HTML — has no browser equivalent and is not
+ * simulated here. A file that passes this mirror can still be refused, and
+ * that refusal renders through the same error contour as any other.
+ *
+ * ── The rule the mirror must never break ───────────────────────────────────
+ *
+ * A MIRROR THAT REFUSES WHAT THE SERVER WOULD ACCEPT IS WORSE THAN NO MIRROR.
+ * It blocks a valid upload with no way for the person to appeal, and the
+ * server never even hears about it. So every ceiling here is CONFIGURABLE on
+ * the runtime and defaults to the library's own default — because all of them
+ * are `STAPEL_CDN` settings a deployment moves (`stapel_cdn/conf.py`), and a
+ * hardcoded 20 MB would be a client-side lie on a host that raised it. The
+ * same argument in the opposite direction: a host that LOWERED the ceiling
+ * passes its number here and gets the refusal early, which is the point.
+ *
+ * The refusals below are raised with stapel-cdn's OWN error codes, so a skin
+ * renders "File is too large" from the generated bundle whether the sentence
+ * came from here or from the server. There is no second vocabulary for
+ * client-side refusals.
+ */
+import { StapelApiError } from "@stapel/core";
+
+/** `error.413.file_too_large` — the byte ceiling, from `MAX_*_SIZE`. */
+export const ERROR_FILE_TOO_LARGE = "error.413.file_too_large";
+/** `error.400.invalid_format` — the extension allowlist. */
+export const ERROR_INVALID_FORMAT = "error.400.invalid_format";
+/** `error.400.no_file` — an empty pick. */
+export const ERROR_NO_FILE = "error.400.no_file";
+
+/**
+ * The ceilings for one intake kind. Defaults reproduce `stapel_cdn/conf.py`'s
+ * `DEFAULTS` at the pinned contract (v0.12.0).
+ */
+export interface CdnIntakeLimits {
+  /** Byte ceiling. `STAPEL_CDN["MAX_IMAGE_SIZE" | …]`. */
+  readonly maxBytes: number;
+  /** Lowercase extensions INCLUDING the dot, as the backend stores them. */
+  readonly extensions: readonly string[];
+  /**
+   * MIME types the backend narrows on, when it narrows on MIME at all. Only
+   * the generic-file intake does (`ALLOWED_FILE_MIME_TYPES`); images and
+   * videos are gated on the extension plus a decode/sniff, so this is
+   * `undefined` for them rather than a guess. An empty array would mean
+   * "nothing is allowed", which is a different and wrong statement.
+   */
+  readonly mimeTypes?: readonly string[];
+}
+
+export interface CdnLimits {
+  readonly image: CdnIntakeLimits;
+  readonly video: CdnIntakeLimits;
+  readonly file: CdnIntakeLimits;
+}
+
+const MB = 1024 * 1024;
+
+/** stapel-cdn's library defaults — the mirror's starting point. */
+export const CDN_DEFAULT_LIMITS: CdnLimits = {
+  image: {
+    maxBytes: 20 * MB,
+    extensions: [".jpg", ".jpeg", ".png", ".gif", ".webp", ".bmp", ".heic", ".heif"],
+  },
+  video: {
+    maxBytes: 100 * MB,
+    extensions: [".mp4", ".webm", ".mov", ".avi", ".mkv"],
+  },
+  file: {
+    maxBytes: 50 * MB,
+    extensions: [
+      ".pdf", ".doc", ".docx", ".xls", ".xlsx", ".ppt", ".pptx",
+      ".txt", ".csv", ".zip", ".rar", ".7z", ".gz",
+    ],
+    mimeTypes: [
+      "application/pdf",
+      "application/msword",
+      "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+      "application/vnd.ms-excel",
+      "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+      "application/vnd.ms-powerpoint",
+      "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+      "text/plain",
+      "text/csv",
+      "application/zip",
+      "application/x-rar-compressed",
+      "application/x-7z-compressed",
+      "application/gzip",
+    ],
+  },
+};
+
+/** Host overrides — every field optional, merged over the defaults. */
+export interface CdnLimitsOverride {
+  readonly image?: Partial<CdnIntakeLimits>;
+  readonly video?: Partial<CdnIntakeLimits>;
+  readonly file?: Partial<CdnIntakeLimits>;
+}
+
+function mergeIntake(
+  base: CdnIntakeLimits,
+  override: Partial<CdnIntakeLimits> | undefined
+): CdnIntakeLimits {
+  if (override === undefined) return base;
+  return {
+    maxBytes: override.maxBytes ?? base.maxBytes,
+    extensions: override.extensions ?? base.extensions,
+    ...(override.mimeTypes !== undefined
+      ? { mimeTypes: override.mimeTypes }
+      : base.mimeTypes !== undefined
+        ? { mimeTypes: base.mimeTypes }
+        : {}),
+  };
+}
+
+export function resolveCdnLimits(override?: CdnLimitsOverride): CdnLimits {
+  return {
+    image: mergeIntake(CDN_DEFAULT_LIMITS.image, override?.image),
+    video: mergeIntake(CDN_DEFAULT_LIMITS.video, override?.video),
+    file: mergeIntake(CDN_DEFAULT_LIMITS.file, override?.file),
+  };
+}
+
+/** The lowercase extension of a filename, dot included, or `""`. */
+export function fileExtension(name: string): string {
+  const dot = name.lastIndexOf(".");
+  if (dot <= 0 || dot === name.length - 1) return "";
+  return name.slice(dot).toLowerCase();
+}
+
+/**
+ * The `accept` attribute for a file input, built from the same allowlist the
+ * refusal is built from — so the picker and the gate cannot disagree.
+ */
+export function acceptAttribute(limits: CdnIntakeLimits): string {
+  const parts = [...limits.extensions];
+  if (limits.mimeTypes !== undefined) parts.push(...limits.mimeTypes);
+  return parts.join(",");
+}
+
+/**
+ * Check one file against one intake's ceilings.
+ *
+ * Returns the refusal as a {@link StapelApiError} in stapel-cdn's own
+ * vocabulary, or `null` when the file may be sent. Never throws: the caller
+ * (a queue admitting ten files at once) needs a per-file verdict, not a
+ * control-flow interruption on the first bad one.
+ */
+export function validateFile(
+  file: File,
+  limits: CdnIntakeLimits
+): StapelApiError | null {
+  if (file.size === 0) {
+    return new StapelApiError({
+      code: ERROR_NO_FILE,
+      message: "No file provided",
+      status: 400,
+    });
+  }
+  if (file.size > limits.maxBytes) {
+    return new StapelApiError({
+      code: ERROR_FILE_TOO_LARGE,
+      message: "File is too large",
+      // The server answers 413 for this; the mirror says the same number so a
+      // host branching on `status` cannot tell the two apart — which is the
+      // intent. `params` carries what the sentence would need to be specific,
+      // even though the backend's own copy has no slots today.
+      status: 413,
+      params: { max_bytes: limits.maxBytes, size: file.size },
+    });
+  }
+  const extension = fileExtension(file.name);
+  if (!limits.extensions.includes(extension)) {
+    return new StapelApiError({
+      code: ERROR_INVALID_FORMAT,
+      message: "Unsupported file format",
+      status: 400,
+      params: { extension, allowed: limits.extensions.join(", ") },
+    });
+  }
+  // MIME is checked only where the backend checks it, and only when the
+  // browser actually supplied one. A blank `file.type` is common (an
+  // extension the OS does not know) and is NOT evidence of a bad file — the
+  // backend reads the declared Content-Type the same way, as a narrowing
+  // device rather than a verdict.
+  if (
+    limits.mimeTypes !== undefined &&
+    file.type.length > 0 &&
+    !limits.mimeTypes.includes(file.type)
+  ) {
+    return new StapelApiError({
+      code: ERROR_INVALID_FORMAT,
+      message: "Unsupported file format",
+      status: 400,
+      params: { mime: file.type },
+    });
+  }
+  return null;
+}

package/src/model/queries.ts

@@ -0,0 +1,64 @@
+import { useQuery } from "@tanstack/react-query";
+import { loadStateFromQuery, useActiveSessionReady } from "@stapel/core";
+import type { LoadState } from "@stapel/core";
+import type { CdnFileExistsResponse, CdnImage, CdnRef } from "../api/types.js";
+import { useCdnApi } from "./context.js";
+import { cdnQueryKeys } from "./queryKeys.js";
+import { parseCdnRef } from "./refs.js";
+
+/**
+ * Resolve a stored `<type>/<hash>` reference back to the CDN row — the read
+ * that lets a composer REOPEN a draft and show what is already attached to it.
+ *
+ * ── The scope this read has, stated rather than discovered ─────────────────
+ *
+ * `file/exists/` filters on `uploaded_by=request.user`, always. So this
+ * resolves the CALLER'S OWN references and nothing else: it is the right
+ * instrument for "my draft's photos" and the wrong one for "this seller's
+ * photos". A buyer's storefront renders a listing's images from what the
+ * listings API gives it, not from here — stapel-cdn exposes no public
+ * read-by-reference endpoint at all (recorded as an upstream gap in the
+ * package README).
+ *
+ * A reference that resolves to nothing answers `ready(null)`, not `failed`:
+ * `{exists: false}` is a 200 and a true answer. "This reference is not mine /
+ * no longer stored" and "we could not ask" are different sentences and a skin
+ * must be able to tell them apart — which is why the value behind `ready` is
+ * nullable and the failure lives in the discriminant.
+ */
+export interface CdnRefBag {
+  readonly state: LoadState<CdnImage | null>;
+  readonly isFetching: boolean;
+  refetch(): void;
+}
+
+export function useCdnRef(ref: CdnRef | null | undefined): CdnRefBag {
+  const api = useCdnApi();
+  // Gated on the session for the reason core's own doc comment gives: the
+  // endpoint is `IsAuthenticated`, so firing it during the login bootstrap
+  // buys one guaranteed 401 per mounted thumbnail.
+  const sessionReady = useActiveSessionReady();
+  const parsed = ref === null || ref === undefined ? null : parseCdnRef(ref);
+
+  const query = useQuery({
+    queryKey: cdnQueryKeys.exists(parsed?.fileHash ?? ""),
+    queryFn: ({ signal }): Promise<CdnFileExistsResponse> =>
+      api.fileExists(parsed?.fileHash ?? "", { signal }),
+    enabled: sessionReady && parsed !== null,
+    // A content-addressed row does not change. Its VARIANTS do, once, when the
+    // background task finishes — the upload flow waits for that itself, so a
+    // refetch here would only re-ask a settled question.
+    staleTime: Number.POSITIVE_INFINITY,
+    retry: false,
+    select: (data): CdnImage | null =>
+      data.exists && data.type === "image" && data.file !== null
+        ? (data.file as CdnImage)
+        : null,
+  });
+
+  return {
+    state: loadStateFromQuery(query),
+    isFetching: query.isFetching,
+    refetch: () => void query.refetch(),
+  };
+}

package/src/model/queryKeys.ts

@@ -0,0 +1,23 @@
+/**
+ * Namespaced TanStack Query keys (frontend-standard §2). Everything under the
+ * `"cdn"` root so a host can invalidate the whole module or match a single
+ * read.
+ *
+ * There is exactly one cached read in this pair, and it is keyed on the CONTENT
+ * HASH rather than on the reference string. Two references that differ only in
+ * asset type (`avatar/<h>` and `product/<h>`) resolve through the same
+ * `file/exists/` call and must not fetch twice; and because the hash IS the
+ * identity of the bytes, a key built from it can never go stale in the way a
+ * mutable row's key can. Uploads are mutations and cache nothing.
+ */
+
+const ROOT = "cdn" as const;
+
+export const cdnQueryKeys: {
+  readonly all: readonly ["cdn"];
+  /** The owner-scoped `file/exists/` read for one content hash. */
+  exists(fileHash: string): readonly ["cdn", "exists", string];
+} = {
+  all: [ROOT],
+  exists: (fileHash) => [ROOT, "exists", fileHash],
+};

package/src/model/refs.ts

@@ -0,0 +1,95 @@
+/**
+ * The `<type>/<hash>` reference — the unit this pair hands out — and the one
+ * conversion between stapel-cdn's variant ladder and `@stapel/image`'s.
+ *
+ * `Profile.avatar` stores a reference. `Listing.images_draft` stores a list of
+ * them ("Opaque list of CDN image references", `stapel_listings/models.py`).
+ * Neither stores a URL, and this pair does not invent one: the reference is
+ * content-addressed and opaque, and the URLs live on the row the CDN returns.
+ */
+import type { StapelImage, VariantMeta } from "@stapel/image";
+import type { CdnImage, CdnRef, ParsedCdnRef } from "../api/types.js";
+
+const HASH = /^[0-9a-f]{64}$/;
+
+/** Build the reference for an asset type and a content hash. */
+export function formatCdnRef(assetType: string, fileHash: string): CdnRef {
+  return `${assetType}/${fileHash}`;
+}
+
+/**
+ * Split a reference into its halves, or `null` when the string is not one.
+ *
+ * Strict about the hash (64 lowercase hex — what the backend writes) and
+ * deliberately loose about the type, which is whatever this deployment put in
+ * `STAPEL_CDN["ASSET_TYPES"]` plus the hardcoded `product` of the general
+ * image endpoint. Rejecting an unfamiliar type here would refuse a host's own
+ * configuration.
+ */
+export function parseCdnRef(ref: CdnRef): ParsedCdnRef | null {
+  const slash = ref.indexOf("/");
+  if (slash <= 0) return null;
+  const assetType = ref.slice(0, slash);
+  const fileHash = ref.slice(slash + 1);
+  if (!HASH.test(fileHash)) return null;
+  return { assetType, fileHash };
+}
+
+/**
+ * Convert an uploaded image row into the source-agnostic descriptor
+ * `@stapel/image`'s `<Image>` consumes.
+ *
+ * THE TWO CONTRACTS DISAGREE ON ONE FIELD AND THIS IS THE ONLY PLACE THAT
+ * KNOWS. stapel-cdn's `variants_meta[].tier` is an integer; `@stapel/image`
+ * reads the `stapel_core.media.dto` form, where `tier` is a decimal STRING
+ * with an `"original"` sentinel. Converting at the boundary costs one map and
+ * keeps both sides honest; teaching either one the other's shape would put a
+ * conditional in every renderer.
+ *
+ * `branch` is optional upstream and absent for thumbnail-class tiers; the
+ * renderer's contract wants an explicit `null` there, which is the same
+ * statement said out loud.
+ *
+ * The type import above is TYPE-ONLY and `@stapel/image` is an OPTIONAL peer:
+ * a host that renders its own images carries no dependency on it and this
+ * function still typechecks, because nothing of it survives to runtime.
+ */
+export function toStapelImage(image: CdnImage): StapelImage {
+  const variants: VariantMeta[] = image.variants_meta.map((variant) => ({
+    tier: String(variant.tier),
+    branch: variant.branch ?? null,
+    url: variant.url,
+    width: variant.width,
+    height: variant.height,
+  }));
+  const width = image.original_width;
+  const height = image.original_height;
+  return {
+    source: "cdn",
+    url: image.original_url,
+    // The CDN row carries the extension, not the MIME type, and the variants
+    // are all WebP regardless of what came in. Saying `null` is the true
+    // statement; guessing a MIME from the extension would be the wrong one.
+    mime: null,
+    width,
+    height,
+    aspect: height > 0 ? width / height : null,
+    square: width === height,
+    // stapel-cdn generates no inline blur placeholder. `<Image>` degrades to
+    // the aspect box, which is the layout-shift protection that actually
+    // matters here.
+    preview_b64: null,
+    variants,
+  };
+}
+
+/**
+ * The reference for an uploaded image row.
+ *
+ * Reads `prefix` — the serializer's own `<type>/<hash>` — rather than
+ * rebuilding it from `type` and `file_hash`, so a host that reconfigures the
+ * layout upstream does not get a reference this pair invented.
+ */
+export function refOf(image: { readonly prefix: string }): CdnRef {
+  return image.prefix;
+}