@stapel/cdn-react 0.1.0

package/dist/model/runtime.js

@@ -0,0 +1,23 @@
+import { createModuleRuntime } from "@stapel/core";
+import { createCdnApi } from "../api/cdnApi.js";
+import { resolveCdnLimits } from "./limits.js";
+/**
+ * ```tsx
+ * const runtime = createCdnRuntime({ baseUrl: "/cdn/api/v1/" });
+ * <CdnProvider runtime={runtime}>{app}</CdnProvider>
+ * ```
+ *
+ * NOT ANONYMOUS. Every endpoint this pair calls needs at least a guest
+ * identity (`IsNotAnonymousUser`), and the avatar intake and the dedup
+ * pre-check need a real session (`IsAuthenticated`). A storefront mounts this
+ * behind its member routes; the public catalogue never touches it.
+ */
+export function createCdnRuntime(options) {
+    const base = createModuleRuntime((client) => createCdnApi(client), options);
+    return {
+        ...base,
+        limits: resolveCdnLimits(options.limits),
+        variants: options.variants,
+    };
+}
+//# sourceMappingURL=runtime.js.map

package/dist/model/runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.js","sourceRoot":"","sources":["../../src/model/runtime.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAEnD,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAEhD,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AA6B/C;;;;;;;;;;GAUG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAgC;IAC/D,MAAM,IAAI,GAAG,mBAAmB,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,YAAY,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,CAAC;IAC5E,OAAO;QACL,GAAG,IAAI;QACP,MAAM,EAAE,gBAAgB,CAAC,OAAO,CAAC,MAAM,CAAC;QACxC,QAAQ,EAAE,OAAO,CAAC,QAAQ;KAC3B,CAAC;AACJ,CAAC"}

package/dist/model/upload.d.ts

@@ -0,0 +1,88 @@
+import type { CdnApi } from "../api/cdnApi.js";
+import type { CdnImage, CdnRef } from "../api/types.js";
+import type { CdnIntakeLimits } from "./limits.js";
+/** Where the bytes go, and therefore what asset type the row gets. */
+export type CdnUploadTarget = {
+    /**
+     * `POST /upload/image/`. The general intake — note that it stores
+     * `type="product"` regardless of `ASSET_TYPES`.
+     */
+    readonly kind: "image";
+} | {
+    /** `POST /upload/avatar/`. The only intake that needs a real session. */
+    readonly kind: "avatar";
+} | {
+    /** `POST /images/<assetType>/upload/`, validated against `ASSET_TYPES`. */
+    readonly kind: "typed";
+    readonly assetType: string;
+};
+/**
+ * The asset type a target produces, which is what the pre-check must match
+ * before it may short-circuit. `"product"` is not a guess: it is the literal
+ * the view writes (`ImageUploadView.post`).
+ */
+export declare function targetAssetType(target: CdnUploadTarget): string;
+/** Which step of the flow is running. */
+export type UploadPhase = "idle" | "hashing" | "checking" | "uploading" | "processing" | "done" | "failed" | "canceled";
+/** Why the dedup pre-check did not happen (or did not answer). */
+export type DedupSkipReason = 
+/** No `crypto.subtle` — this page is not a secure context. */
+"no_crypto"
+/** `file/exists/` needs `IsAuthenticated`; a guest identity may still upload. */
+ | "unauthorized"
+/** The check itself failed. Never fatal: the upload proceeds. */
+ | "check_failed"
+/** The caller asked for no pre-check. */
+ | "disabled";
+/** What a finished upload yields. */
+export interface UploadOutcome {
+    /** `<type>/<hash>` — the value a consuming module stores. */
+    readonly ref: CdnRef;
+    readonly image: CdnImage;
+    /** The pre-check hit and NO upload request was made. */
+    readonly deduped: boolean;
+    /** `undefined` when the pre-check ran; a reason when it did not. */
+    readonly dedupSkipped: DedupSkipReason | undefined;
+    /**
+     * Whether the variant ladder had been generated by the time the flow
+     * stopped waiting. `false` is not a failure — variants are produced by a
+     * background task and the reference is valid immediately; it means a skin
+     * should show the original (or its own placeholder) for now.
+     */
+    readonly variantsReady: boolean;
+}
+export interface RunUploadOptions {
+    readonly target: CdnUploadTarget;
+    readonly limits: CdnIntakeLimits;
+    readonly signal?: AbortSignal;
+    /** Phase transitions, in order. Called synchronously. */
+    readonly onPhase?: (phase: UploadPhase) => void;
+    /** Skip the pre-check entirely (reported as `dedupSkipped: "disabled"`). */
+    readonly dedup?: boolean;
+    /** How long to wait for the variant ladder. Default: 8 tries, 750 ms apart. */
+    readonly variants?: CdnVariantWaitOptions;
+}
+export interface CdnVariantWaitOptions {
+    /** `0` disables waiting; the outcome then reports the row as it arrived. */
+    readonly attempts?: number;
+    readonly intervalMs?: number;
+    /** Injectable timer (tests). Default: `setTimeout`. */
+    readonly wait?: (ms: number, signal?: AbortSignal) => Promise<void>;
+}
+/** The abort a caller asked for, told apart from a genuine transport fault. */
+export declare class UploadCanceled extends Error {
+    constructor();
+}
+export declare function isUploadCanceled(value: unknown): value is UploadCanceled;
+/**
+ * Run the whole flow for one file.
+ *
+ * Rejects with a {@link StapelApiError} for every failure that is one — the
+ * client-side refusal, the server's, a transport fault folded by
+ * `toStapelApiError` — and with {@link UploadCanceled} when the signal fired.
+ * A caller therefore branches on cancellation without having to recognise
+ * `AbortError` by name, which is a DOMException whose shape differs between
+ * runtimes.
+ */
+export declare function runUpload(api: CdnApi, file: File, options: RunUploadOptions): Promise<UploadOutcome>;
+//# sourceMappingURL=upload.d.ts.map

package/dist/model/upload.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"upload.d.ts","sourceRoot":"","sources":["../../src/model/upload.ts"],"names":[],"mappings":"AA6CA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAGxD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAGnD,sEAAsE;AACtE,MAAM,MAAM,eAAe,GACvB;IACE;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;CACxB,GACD;IACE,yEAAyE;IACzE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;CACzB,GACD;IACE,2EAA2E;IAC3E,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B,CAAC;AAEN;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM,CAS/D;AAED,yCAAyC;AACzC,MAAM,MAAM,WAAW,GACnB,MAAM,GACN,SAAS,GACT,UAAU,GACV,WAAW,GACX,YAAY,GACZ,MAAM,GACN,QAAQ,GACR,UAAU,CAAC;AAEf,kEAAkE;AAClE,MAAM,MAAM,eAAe;AACzB,8DAA8D;AAC5D,WAAW;AACb,iFAAiF;GAC/E,cAAc;AAChB,iEAAiE;GAC/D,cAAc;AAChB,yCAAyC;GACvC,UAAU,CAAC;AAEf,qCAAqC;AACrC,MAAM,WAAW,aAAa;IAC5B,6DAA6D;IAC7D,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC;IACzB,wDAAwD;IACxD,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,oEAAoE;IACpE,QAAQ,CAAC,YAAY,EAAE,eAAe,GAAG,SAAS,CAAC;IACnD;;;;;OAKG;IACH,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;CACjC;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC;IACjC,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC;IACjC,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAC9B,yDAAyD;IACzD,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,CAAC;IAChD,4EAA4E;IAC5E,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB,+EAA+E;IAC/E,QAAQ,CAAC,QAAQ,CAAC,EAAE,qBAAqB,CAAC;CAC3C;AAED,MAAM,WAAW,qBAAqB;IACpC,4EAA4E;IAC5E,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,uDAAuD;IACvD,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACrE;AA+BD,+EAA+E;AAC/E,qBAAa,cAAe,SAAQ,KAAK;;CAKxC;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,cAAc,CAExE;AAMD;;;;;;;;;GASG;AACH,wBAAsB,SAAS,CAC7B,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,IAAI,EACV,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,aAAa,CAAC,CA4FxB"}

package/dist/model/upload.js

@@ -0,0 +1,254 @@
+/**
+ * The dedup-first upload flow — the one piece of business this pair exists
+ * for, written once, with no React in it.
+ *
+ * ```
+ *  validate ─┬─ refuse (client-side mirror, cdn's own error codes)
+ *            │
+ *            └─ hash ── check `file/exists/` ─┬─ HIT  → done, ZERO bytes sent
+ *                                             │
+ *                                             └─ MISS → POST multipart
+ *                                                        └─ poll for variants
+ * ```
+ *
+ * ── Why the phases are named and not a percentage ──────────────────────────
+ *
+ * There is no honest byte-percentage to report. `fetch` cannot observe how
+ * much of a request body has gone out (only a `ReadableStream` body with
+ * `duplex: "half"` can, and that is neither universal nor reachable through
+ * the injected client), and `crypto.subtle.digest` reports nothing between
+ * "started" and "finished". The two ways to have a moving bar anyway are to
+ * fork the transport onto `XMLHttpRequest` — which means re-implementing the
+ * client's bearer/refresh/verification/error seams, i.e. a second transport
+ * with its own bugs — or to animate a number that is not measured. This
+ * package does neither: `UploadPhase` says which step is running, and a skin
+ * shows an indeterminate indicator during the two steps whose duration is
+ * real. Naming the step the person is waiting on is more information than a
+ * bar that is lying, and it is the same rule the rest of this fleet applies to
+ * counts it did not compute.
+ *
+ * ── What the pre-check can and cannot promise ──────────────────────────────
+ *
+ * A HIT is a promise: the bytes are already stored, under this caller's
+ * ownership, as the asset type being uploaded — so the POST is skipped and the
+ * reference is handed back immediately. That is the property spec §8.2 asks to
+ * be tested, and `test/dedup.test.ts` asserts it by counting requests.
+ *
+ * A MISS is not a promise of the opposite. `file/exists/` filters on
+ * `uploaded_by=request.user` unconditionally, while the upload paths honour
+ * `STAPEL_CDN["DEDUP_SCOPE"]` (default `"owner"`, optionally `"global"`), so
+ * under a global scope the POST can still answer 200 "already exists". Nothing
+ * downstream cares — the same body comes back either way — but this is why
+ * `deduped` reports what THIS CLIENT observed rather than claiming to know
+ * what the server did with the bytes.
+ */
+import { toStapelApiError } from "@stapel/core";
+import { canHashLocally, sha256Hex } from "./hash.js";
+import { validateFile } from "./limits.js";
+import { refOf } from "./refs.js";
+/**
+ * The asset type a target produces, which is what the pre-check must match
+ * before it may short-circuit. `"product"` is not a guess: it is the literal
+ * the view writes (`ImageUploadView.post`).
+ */
+export function targetAssetType(target) {
+    switch (target.kind) {
+        case "image":
+            return "product";
+        case "avatar":
+            return "avatar";
+        case "typed":
+            return target.assetType;
+    }
+}
+const DEFAULT_VARIANT_ATTEMPTS = 8;
+const DEFAULT_VARIANT_INTERVAL_MS = 750;
+/**
+ * Named, not inlined, for the same reason `stapel/no-adhoc-401` names it in
+ * its own source: the rule bans a bare `=== 401` because that shape is how ad
+ * hoc refresh/redirect logic gets written outside core's one seam. What
+ * happens below is not that — nothing is refreshed, retried or redirected;
+ * a 401 from the OPTIONAL pre-check is merely CLASSIFIED, so the outcome can
+ * say "a guest may upload but may not pre-check" instead of "the check
+ * failed". The real 401 handling stays where it belongs, on the client's
+ * `onAuthRefresh` seam, and this flow never sees it.
+ */
+const HTTP_UNAUTHORIZED = 401;
+function defaultWait(ms, signal) {
+    return new Promise((resolve) => {
+        const timer = setTimeout(resolve, ms);
+        signal?.addEventListener("abort", () => {
+            clearTimeout(timer);
+            resolve();
+        }, { once: true });
+    });
+}
+/** The abort a caller asked for, told apart from a genuine transport fault. */
+export class UploadCanceled extends Error {
+    constructor() {
+        super("Upload canceled");
+        this.name = "UploadCanceled";
+    }
+}
+export function isUploadCanceled(value) {
+    return value instanceof UploadCanceled;
+}
+function throwIfAborted(signal) {
+    if (signal?.aborted === true)
+        throw new UploadCanceled();
+}
+/**
+ * Run the whole flow for one file.
+ *
+ * Rejects with a {@link StapelApiError} for every failure that is one — the
+ * client-side refusal, the server's, a transport fault folded by
+ * `toStapelApiError` — and with {@link UploadCanceled} when the signal fired.
+ * A caller therefore branches on cancellation without having to recognise
+ * `AbortError` by name, which is a DOMException whose shape differs between
+ * runtimes.
+ */
+export async function runUpload(api, file, options) {
+    const { target, limits, signal } = options;
+    const phase = (next) => options.onPhase?.(next);
+    throwIfAborted(signal);
+    const refusal = validateFile(file, limits);
+    if (refusal !== null) {
+        phase("failed");
+        throw refusal;
+    }
+    const assetType = targetAssetType(target);
+    let fileHash = null;
+    let dedupSkipped;
+    if (options.dedup === false) {
+        dedupSkipped = "disabled";
+    }
+    else if (!canHashLocally()) {
+        dedupSkipped = "no_crypto";
+    }
+    else {
+        phase("hashing");
+        fileHash = await sha256Hex(file);
+        throwIfAborted(signal);
+        phase("checking");
+        try {
+            const found = await api.fileExists(fileHash, sig(signal));
+            throwIfAborted(signal);
+            // Three conditions, all required. `exists` alone is not enough: the
+            // endpoint answers about ANY object with these bytes, so the same file
+            // stored earlier as a video or a document reports a hit that is not an
+            // image at all. And an image of a DIFFERENT asset type is not the row
+            // this POST would return either — the upload views filter dedup on
+            // `type=`, so uploading the bytes of one's own avatar as a listing photo
+            // must really upload them.
+            if (found.exists && found.type === "image" && found.file !== null) {
+                const image = found.file;
+                if (image.type === assetType) {
+                    phase("done");
+                    return {
+                        ref: refOf(image),
+                        image,
+                        deduped: true,
+                        dedupSkipped: undefined,
+                        variantsReady: image.is_processed,
+                    };
+                }
+            }
+        }
+        catch (error) {
+            if (isUploadCanceled(error))
+                throw error;
+            const failure = toStapelApiError(error);
+            // 401 is the documented asymmetry: `file/exists/` needs
+            // `IsAuthenticated` while the upload endpoints take
+            // `IsNotAnonymousUser`, so a guest legitimately reaches this line and
+            // must still be able to upload. Every other failure is treated the same
+            // way for the same reason — the pre-check is an OPTIMISATION, and an
+            // optimisation that can fail the operation it optimises is a defect.
+            dedupSkipped =
+                failure.status === HTTP_UNAUTHORIZED ? "unauthorized" : "check_failed";
+        }
+    }
+    throwIfAborted(signal);
+    phase("uploading");
+    let image;
+    try {
+        const response = await uploadTo(api, target, file, signal);
+        image = response.image;
+    }
+    catch (error) {
+        if (signal?.aborted === true) {
+            phase("canceled");
+            throw new UploadCanceled();
+        }
+        phase("failed");
+        throw toStapelApiError(error);
+    }
+    const settled = await waitForVariants(api, image, {
+        ...(signal !== undefined ? { signal } : {}),
+        ...(options.variants !== undefined ? { variants: options.variants } : {}),
+        onPhase: phase,
+    });
+    phase("done");
+    return {
+        ref: refOf(settled),
+        image: settled,
+        deduped: false,
+        dedupSkipped,
+        variantsReady: settled.is_processed,
+    };
+}
+function sig(signal) {
+    return signal !== undefined ? { signal } : {};
+}
+function uploadTo(api, target, file, signal) {
+    switch (target.kind) {
+        case "avatar":
+            return api.uploadAvatar(file, sig(signal));
+        case "typed":
+            return api.uploadTypedImage(target.assetType, file, sig(signal));
+        case "image":
+            return api.uploadImage(file, sig(signal));
+    }
+}
+/**
+ * Wait for the background task to produce the variant ladder, by re-asking
+ * `file/exists/` — which is the only read stapel-cdn offers for a stored row.
+ *
+ * Bounded, and bounded is the point: variants are generated by a worker that
+ * may be down, and a polling loop with no ceiling turns "the thumbnail is not
+ * ready yet" into a tab that never stops making requests. When the budget runs
+ * out the flow returns the row it has, with `variantsReady: false` — a stated
+ * outcome, not a hang and not a failure. The reference is already valid.
+ */
+async function waitForVariants(api, image, options) {
+    if (image.is_processed)
+        return image;
+    const attempts = options.variants?.attempts ?? DEFAULT_VARIANT_ATTEMPTS;
+    if (attempts <= 0)
+        return image;
+    const intervalMs = options.variants?.intervalMs ?? DEFAULT_VARIANT_INTERVAL_MS;
+    const wait = options.variants?.wait ?? defaultWait;
+    options.onPhase("processing");
+    let latest = image;
+    for (let attempt = 0; attempt < attempts; attempt += 1) {
+        await wait(intervalMs, options.signal);
+        if (options.signal?.aborted === true)
+            return latest;
+        try {
+            const found = await api.fileExists(latest.file_hash, sig(options.signal));
+            if (found.exists && found.type === "image" && found.file !== null) {
+                latest = found.file;
+                if (latest.is_processed)
+                    return latest;
+            }
+        }
+        catch {
+            // Same posture as the pre-check: the ladder is an enhancement of a row
+            // that already exists. A failed poll ends the wait and reports the row
+            // as unprocessed; it never turns a stored upload into a failed one.
+            return latest;
+        }
+    }
+    return latest;
+}
+//# sourceMappingURL=upload.js.map

package/dist/model/upload.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"upload.js","sourceRoot":"","sources":["../../src/model/upload.ts"],"names":[],"mappings":"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"}

package/llms.txt

@@ -0,0 +1,83 @@
+# @stapel/cdn-react 0.1.0
+
+Headless React flow pair for stapel-cdn (contract >=0.12 <0.13) — business + state, zero visual opinion.
+Built on @stapel/core: typed client + StapelApiError envelope, auth token refresh,
+verification-403 interception, i18n engine, analytics facade, TanStack Query layer.
+
+## The one right way (do this, the rest is a review/lint smell)
+- No raw fetch/axios. The client is injected via <CdnProvider>/StapelConfigProvider;
+  every hook and flow already carries auth, refresh, and the error envelope.
+- Render errors, never try/catch them: a flow's state carries FlowError{code,params};
+  render `t(code, params)` and branch on `explainCdnError(code)` remediation.
+- Server state = the use* hooks (query layer); keys come only from cdnQueryKeys.
+- User strings = i18n keys (registerCdnI18n); never string literals.
+- Sign-in UI = a headless flow component; copy it (shadcn-style) to restyle.
+
+## Layers
+api (typed client) · model (hooks, session) · flows (machines) · headless · i18n
+
+## Documented flows (flows.json — canonical id, steps, endpoints)
+
+## Operations (typed; use the named op, never a path string)
+Request/response schema names are in manifest.json + the generated types.
+Paths are relative to `/cdn/api/v1/`.
+- check_file_exists_get: GET /file/exists/
+- check_file_exists_post: POST /file/exists/
+- random_image: GET /images/{image_type}/random/
+- sync_refs: POST /refs/sync/
+- upload_avatar: POST /upload/avatar/
+- upload_file: POST /upload/file/
+- upload_image: POST /upload/image/
+- upload_typed_image: POST /images/{image_type}/upload/
+- upload_video: POST /upload/video/
+
+## Query hooks (server state; keys come only from the key factory)
+- useCdnRef (query) → fileExists
+
+## Errors (render t(code, params); UX from remediation)
+53 keys (full catalog: manifest.json §errors). By remediation: fix_input 24 · retry 15 · verify 5 · wait_and_retry 5 · contact_support 3 · reauthenticate 1.
+Param-bearing keys (interpolation slots matter):
+- error.400.field.blank [400] → fix_input {field}
+- error.400.field.does_not_exist [400] → fix_input {field}
+- error.400.field.invalid [400] → fix_input {field}
+- error.400.field.invalid_choice [400] → fix_input {field}
+- error.400.field.max_length [400] → fix_input {field,max_length}
+- error.400.field.max_value [400] → fix_input {field,max_value}
+- error.400.field.min_length [400] → fix_input {field,min_length}
+- error.400.field.min_value [400] → fix_input {field,min_value}
+- error.400.field.null [400] → fix_input {field}
+- error.400.field.required [400] → fix_input {field}
+- error.400.field.unique [400] → fix_input {field}
+- error.429.rate_limit [429] → wait_and_retry {retry_after_minutes}
+- error.503.image_decoder_unavailable [503] → contact_support {extension}
+
+## Analytics events (typed; defineEvent → events.json, drift-gated)
+- (no app defineEvent() in this pair — its analytic events are the
+  auto-instrumented flow funnels below)
+
+## Flow funnels (auto-instrumented: flow.<id>.<step> {phase})
+
+```tsx
+// Typed event + tracked() click (the one right way; §3.1).
+const planSelected = defineEvent({
+  name: "pricing.plan.selected",
+  description: "User picked a plan",
+  props: { plan: prop.oneOf(["free", "pro", "team"], "Plan code") },
+});
+const { tracked } = useTracked();
+<Button onClick={tracked(planSelected, { plan }, startCheckout)} />
+// A click that STEPS a flow machine is already instrumented — mark it
+// data-analytics="flow" instead; tracked() on top double-counts (§3.2).
+```
+
+## Demos (defineDemo → manifest.demos; compiled, linted, rendered examples)
+- cdn.gallery → <MediaUploader> [default|reopened-draft|full]  demo/MediaUploader.demo.tsx
+- cdn.single → <ImageUpload> [default|already-stored]  demo/ImageUpload.demo.tsx
+Each source file is the canonical usage snippet (open the default variant).
+
+## Snippets
+```tsx
+// Error rendering + remediation branch (one pattern for every pair).
+const r = explainCdnError(err.code); // 'wait_and_retry' | 'verify' | ...
+return <Alert action={r}>{t(err.code, err.params)}</Alert>;
+```