@mohasinac/appkit 4.52.5 → 4.53.1

package/dist/features/media/trust-signals.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Provenance signals on uploaded imagery — plan A7.
+ *
+ * ## 🛑 A FLAG, never a rejection
+ *
+ * Nothing here blocks an upload or hides a listing. Every signal is recorded
+ * on the `mediaAssets` row for a human to look at, because every one of them
+ * has a legitimate explanation: a seller may genuinely own the Amazon listing
+ * the photo came from, and an AI-generated image is a reasonable choice for an
+ * art listing's mock-up. Auto-rejecting on a heuristic means refusing honest
+ * sellers on a filename.
+ *
+ * ## What is grounded in measurement
+ *
+ * From the fifteen-site competitor crawl
+ * (`docs/research/competitor-crawl-2026-10/images.md`):
+ *
+ *   bladekingbeys — **138 images named with Amazon's CDN pattern**
+ *                   (`..._AC_SL1500_.jpg`) plus `ChatGPT-Image-*.png` files.
+ *                   A storefront built from other people's product shots.
+ *
+ * ## 🛑 What is deliberately NOT a signal
+ *
+ * `rn-image_picker_lib_temp_*` (React Native's image picker) and
+ * `WhatsApp-Image-*` are what REAL sellers' uploads look like — measured,
+ * toycollectorsindia and beyyuniverse upload exactly that way, and
+ * beyyuniverse's entire catalogue is `WhatsApp-Image-*.jpeg`. Flagging them
+ * would put a flag on nearly every honest phone upload, which trains
+ * moderators to dismiss the queue — and a queue nobody reads is worse than no
+ * queue, because it looks like oversight.
+ *
+ * That asymmetry is the whole design: flag the patterns that indicate the
+ * image came from someone ELSE'S listing, never the ones that merely indicate
+ * it came from a phone.
+ */
+/** One recorded provenance concern. Stable strings — they are persisted. */
+export declare const MEDIA_TRUST_FLAG: {
+    /** Filename carries Amazon's CDN size suffix, e.g. `..._AC_SL1500_.jpg`. */
+    readonly AMAZON_CDN_FILENAME: "amazon-cdn-filename";
+    /** Filename is an AI image generator's default output name. */
+    readonly AI_GENERATED_FILENAME: "ai-generated-filename";
+    /**
+     * Byte-level near-duplicate of an image a DIFFERENT uploader already has.
+     *
+     * Same-uploader duplicates are normal and are NOT flagged — a seller
+     * reusing one photo across their own variants is ordinary behaviour.
+     */
+    readonly CROSS_SELLER_DUPLICATE: "cross-seller-duplicate";
+};
+export type MediaTrustFlag = (typeof MEDIA_TRUST_FLAG)[keyof typeof MEDIA_TRUST_FLAG];
+/**
+ * Provenance flags derivable from the filename alone.
+ *
+ * Takes the ORIGINAL client filename, not the storage path — our own paths are
+ * content-derived slugs (§ Media Filename Slug Patterns) and carry none of
+ * this.
+ */
+export declare function filenameTrustFlags(originalFilename: string | undefined | null): MediaTrustFlag[];
+/**
+ * Hamming distance between two hex dHashes — the number of differing bits.
+ *
+ * 0 is byte-identical-after-downscale; under ~5 is "the same photograph,
+ * re-encoded or lightly cropped". Returns `null` when the two cannot be
+ * compared (different lengths, non-hex), because a fabricated distance would
+ * feed a flag.
+ */
+export declare function dHashDistance(a: string | undefined, b: string | undefined): number | null;
+/**
+ * How close two dHashes must be to count as the same photograph.
+ *
+ * 🛑 Deliberately TIGHT, and the number comes from measurement rather than
+ * from the usual "distance < 10" folklore. Against one real catalogue image:
+ *
+ *     resized to 220px wide    -> 0
+ *     re-encoded jpeg q55      -> 3
+ *     a DIFFERENT bey          -> 9
+ *
+ * So the usable gap is 3-vs-9, which is real but not generous: product
+ * photography is self-similar (same item class, same white background, same
+ * angle), so a loose threshold here is a flag GENERATOR rather than a signal,
+ * and a queue full of false flags is worse than no queue because it looks like
+ * oversight. 5 sits above the re-encode and well below the different-item
+ * case.
+ */
+export declare const DHASH_DUPLICATE_MAX_DISTANCE = 5;

package/dist/features/media/trust-signals.js

@@ -0,0 +1,126 @@
+/**
+ * Provenance signals on uploaded imagery — plan A7.
+ *
+ * ## 🛑 A FLAG, never a rejection
+ *
+ * Nothing here blocks an upload or hides a listing. Every signal is recorded
+ * on the `mediaAssets` row for a human to look at, because every one of them
+ * has a legitimate explanation: a seller may genuinely own the Amazon listing
+ * the photo came from, and an AI-generated image is a reasonable choice for an
+ * art listing's mock-up. Auto-rejecting on a heuristic means refusing honest
+ * sellers on a filename.
+ *
+ * ## What is grounded in measurement
+ *
+ * From the fifteen-site competitor crawl
+ * (`docs/research/competitor-crawl-2026-10/images.md`):
+ *
+ *   bladekingbeys — **138 images named with Amazon's CDN pattern**
+ *                   (`..._AC_SL1500_.jpg`) plus `ChatGPT-Image-*.png` files.
+ *                   A storefront built from other people's product shots.
+ *
+ * ## 🛑 What is deliberately NOT a signal
+ *
+ * `rn-image_picker_lib_temp_*` (React Native's image picker) and
+ * `WhatsApp-Image-*` are what REAL sellers' uploads look like — measured,
+ * toycollectorsindia and beyyuniverse upload exactly that way, and
+ * beyyuniverse's entire catalogue is `WhatsApp-Image-*.jpeg`. Flagging them
+ * would put a flag on nearly every honest phone upload, which trains
+ * moderators to dismiss the queue — and a queue nobody reads is worse than no
+ * queue, because it looks like oversight.
+ *
+ * That asymmetry is the whole design: flag the patterns that indicate the
+ * image came from someone ELSE'S listing, never the ones that merely indicate
+ * it came from a phone.
+ */
+/** One recorded provenance concern. Stable strings — they are persisted. */
+export const MEDIA_TRUST_FLAG = {
+    /** Filename carries Amazon's CDN size suffix, e.g. `..._AC_SL1500_.jpg`. */
+    AMAZON_CDN_FILENAME: "amazon-cdn-filename",
+    /** Filename is an AI image generator's default output name. */
+    AI_GENERATED_FILENAME: "ai-generated-filename",
+    /**
+     * Byte-level near-duplicate of an image a DIFFERENT uploader already has.
+     *
+     * Same-uploader duplicates are normal and are NOT flagged — a seller
+     * reusing one photo across their own variants is ordinary behaviour.
+     */
+    CROSS_SELLER_DUPLICATE: "cross-seller-duplicate",
+};
+/*
+ * `_AC_` is Amazon's image-transform marker and `_SL<digits>_` its size
+ * directive; together they are unmistakable and do not occur in ordinary
+ * filenames. Matching `_AC_` alone would false-positive on anything with those
+ * letters between underscores.
+ */
+const AMAZON_CDN_RX = /_AC_[A-Z]{0,4}\d*_|_SL\d{3,4}_/;
+/*
+ * Default output names from the common generators. Anchored to the START so a
+ * seller who writes "chatgpt-image-of-my-bey.jpg" by hand is not caught by a
+ * substring — the signal is "this is the tool's untouched default", not "the
+ * word appears".
+ */
+const AI_FILENAME_RX = /^(?:chatgpt-image-|dall[·e-]*e-|midjourney_|stable-?diffusion-|gemini-generated-image)/i;
+/**
+ * Provenance flags derivable from the filename alone.
+ *
+ * Takes the ORIGINAL client filename, not the storage path — our own paths are
+ * content-derived slugs (§ Media Filename Slug Patterns) and carry none of
+ * this.
+ */
+export function filenameTrustFlags(originalFilename) {
+    if (!originalFilename)
+        return [];
+    const name = originalFilename.trim();
+    if (!name)
+        return [];
+    const flags = [];
+    if (AMAZON_CDN_RX.test(name))
+        flags.push(MEDIA_TRUST_FLAG.AMAZON_CDN_FILENAME);
+    if (AI_FILENAME_RX.test(name))
+        flags.push(MEDIA_TRUST_FLAG.AI_GENERATED_FILENAME);
+    return flags;
+}
+/**
+ * Hamming distance between two hex dHashes — the number of differing bits.
+ *
+ * 0 is byte-identical-after-downscale; under ~5 is "the same photograph,
+ * re-encoded or lightly cropped". Returns `null` when the two cannot be
+ * compared (different lengths, non-hex), because a fabricated distance would
+ * feed a flag.
+ */
+export function dHashDistance(a, b) {
+    if (!a || !b || a.length !== b.length)
+        return null;
+    let distance = 0;
+    for (let i = 0; i < a.length; i += 1) {
+        const x = Number.parseInt(a[i], 16);
+        const y = Number.parseInt(b[i], 16);
+        if (Number.isNaN(x) || Number.isNaN(y))
+            return null;
+        let diff = x ^ y;
+        while (diff) {
+            distance += diff & 1;
+            diff >>= 1;
+        }
+    }
+    return distance;
+}
+/**
+ * How close two dHashes must be to count as the same photograph.
+ *
+ * 🛑 Deliberately TIGHT, and the number comes from measurement rather than
+ * from the usual "distance < 10" folklore. Against one real catalogue image:
+ *
+ *     resized to 220px wide    -> 0
+ *     re-encoded jpeg q55      -> 3
+ *     a DIFFERENT bey          -> 9
+ *
+ * So the usable gap is 3-vs-9, which is real but not generous: product
+ * photography is self-similar (same item class, same white background, same
+ * angle), so a loose threshold here is a flag GENERATOR rather than a signal,
+ * and a queue full of false flags is worse than no queue because it looks like
+ * oversight. 5 sits above the re-encode and well below the different-item
+ * case.
+ */
+export const DHASH_DUPLICATE_MAX_DISTANCE = 5;

package/dist/features/media/upload/CameraCapture.js

@@ -9,7 +9,22 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useEffect, useState } from "react";
 import { useTranslations } from "next-intl";
 import { useCamera } from "../../../react/index.js";
-import { Alert, Button, Div, Row, Span, Spinner, Stack } from "../../../ui/index.js";
+/*
+ * Defining modules, not the `ui` barrel — Root Cause #18.
+ *
+ * `ui/index.ts` re-exports `FormField`, `PaginatedSelect` and
+ * `RecordDetailModal`, and those three import back INTO `features/media` and
+ * `features/shell`. So reaching a primitive through the barrel closed a
+ * ten-module cycle (`audit-import-cycles` component 1) — while the deep paths
+ * below have one direction only. `ui → features/media` is the real dependency
+ * and it stays; the barrel hop is what did not need to exist.
+ */
+import { Alert } from "../../../ui/components/Alert.js";
+import { Button } from "../../../ui/components/Button.js";
+import { Div } from "../../../ui/components/Div.js";
+import { Row, Stack } from "../../../ui/components/Layout.js";
+import { Spinner } from "../../../ui/components/Spinner.js";
+import { Span } from "../../../ui/components/Typography.js";
 export default function CameraCapture({ mode, facingMode = "environment", onCapture, onError, className, }) {
     const t = useTranslations("camera");
     const camera = useCamera();

package/dist/features/media/upload/ImageUpload.js

@@ -1,6 +1,7 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
-import { IMAGE_ACCEPT_ATTR } from "../../../_internal/shared/media/limits.js";
+import { IMAGE_ACCEPT_ATTR, MAX_IMAGE_BYTES, MEGABYTE, } from "../../../_internal/shared/media/limits.js";
+import { downscaleImageFile } from "./downscale-image.js";
 import { normalizeError } from "../../../errors/normalize.js";
 /**
  * ImageUpload — canonical image upload component for @mohasinac/feat-media.
@@ -13,7 +14,24 @@ import { useState, useRef } from "react";
 import dynamic from "next/dynamic.js";
 import { useTranslations } from "next-intl";
 import { useCamera } from "../../../react/index.js";
-import { Alert, Button, Div, Label, Progress, Row, Spinner, Stack, Text, useToast } from "../../../ui/index.js";
+/*
+ * Defining modules, not the `ui` barrel — Root Cause #18.
+ *
+ * `ui/index.ts` re-exports `FormField`, `PaginatedSelect` and
+ * `RecordDetailModal`, and those three import back INTO `features/media` and
+ * `features/shell`. So reaching a primitive through the barrel closed a
+ * ten-module cycle (`audit-import-cycles` component 1) — while the deep paths
+ * below have one direction only. `ui → features/media` is the real dependency
+ * and it stays; the barrel hop is what did not need to exist.
+ */
+import { Alert } from "../../../ui/components/Alert.js";
+import { Button } from "../../../ui/components/Button.js";
+import { Div } from "../../../ui/components/Div.js";
+import { Row, Stack } from "../../../ui/components/Layout.js";
+import { Progress } from "../../../ui/components/Progress.js";
+import { Spinner } from "../../../ui/components/Spinner.js";
+import { Label, Text } from "../../../ui/components/Typography.js";
+import { useToast } from "../../../ui/components/toast-context.js";
 import { MediaImage } from "../MediaImage.js";
 import CameraCapture from "./CameraCapture.js";
 // Crop/editor modals pull in image-manipulation libraries (react-advanced-cropper
@@ -40,7 +58,12 @@ function matchesMimeAccept(fileType, accept) {
         return pSub === "*" || pSub === fSub;
     });
 }
-export function ImageUpload({ currentImage, onUpload, onChange, accept = "image/*", maxSizeMB = 10, label = "Upload Image", helperText, captureSource = "both", enableCrop = true, enableAdvancedCrop = false, cropAspectRatio, onCropDataChange, }) {
+export function ImageUpload({ currentImage, onUpload, onChange, 
+// 🛑 Never `image/*` — that wildcard matches `image/svg+xml`, which
+// `ALLOWED_IMAGE_MIMES` deliberately excludes as an XSS surface and which the
+// server 422s only after the crop editor has already opened on it. See
+// `IMAGE_ACCEPT_ATTR`'s own docstring in `_internal/shared/media/limits.ts`.
+accept = IMAGE_ACCEPT_ATTR, maxSizeMB = MAX_IMAGE_BYTES / MEGABYTE, label = "Upload Image", helperText, captureSource = "both", enableCrop = true, enableAdvancedCrop = false, cropAspectRatio, onCropDataChange, }) {
     const [uploading, setUploading] = useState(false);
     const [preview, setPreview] = useState(currentImage || "");
     const [error, setError] = useState("");
@@ -65,7 +88,22 @@ export function ImageUpload({ currentImage, onUpload, onChange, accept = "image/
         try {
             setUploading(true);
             setProgress(30);
-            const url = await onUpload(file);
+            /*
+             * The single choke point for all six upload paths (direct, crop-save,
+             * crop-close, advanced-save, advanced-close, camera), so bounding the
+             * master here covers every one.
+             *
+             * 🛑 Safe to apply even when `cropData` is present: `ImageCropData` is
+             * `{ position, zoom }` in CSS PERCENTAGES — the modal's own header says
+             * "Returns CSS position/zoom percentages" and applies them as
+             * `left: ${position.x}%` — so it is scale-invariant and a uniform
+             * downscale cannot misalign a crop. Pixel-rect crop data would not be.
+             *
+             * A file already produced by `ImageEditor` comes back untouched (it is
+             * webp within 2048 already), so there is no double re-encode.
+             */
+            const prepared = await downscaleImageFile(file);
+            const url = await onUpload(prepared);
             setProgress(100);
             setPreview(url);
             onChange?.(url);

package/dist/features/media/upload/MediaUploadField.js

@@ -9,14 +9,32 @@ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-run
 import { useState, useRef, useEffect } from "react";
 import { useTranslations } from "next-intl";
 import { useCamera } from "../../../react/index.js";
-import { Alert, Anchor, Button, Div, Label, Row, Span, Spinner, Stack, Text } from "../../../ui/index.js";
+/*
+ * Defining modules, not the `ui` barrel — Root Cause #18.
+ *
+ * `ui/index.ts` re-exports `FormField`, `PaginatedSelect` and
+ * `RecordDetailModal`, and those three import back INTO `features/media` and
+ * `features/shell`. So reaching a primitive through the barrel closed a
+ * ten-module cycle (`audit-import-cycles` component 1) — while the deep paths
+ * below have one direction only. `ui → features/media` is the real dependency
+ * and it stays; the barrel hop is what did not need to exist.
+ */
+import { Alert } from "../../../ui/components/Alert.js";
+import { Anchor } from "../../../ui/components/Anchor.js";
+import { Button } from "../../../ui/components/Button.js";
+import { Div } from "../../../ui/components/Div.js";
+import { Row, Stack } from "../../../ui/components/Layout.js";
+import { Spinner } from "../../../ui/components/Spinner.js";
+import { Label, Span, Text } from "../../../ui/components/Typography.js";
 import { MediaImage } from "../MediaImage.js";
 import { MediaVideo } from "../MediaVideo.js";
 import dynamic from "next/dynamic.js";
 import { VideoThumbnailSelector } from "../modals/VideoThumbnailSelector.js";
 import CameraCapture from "./CameraCapture.js";
 import { extractVideoPosterFrame, posterBlobAsFile } from "./video-poster.js";
+import { downscaleImageFile } from "./downscale-image.js";
 import { inferMediaTypeFromMime } from "../types/index.js";
+import { ALLOWED_DOC_MIMES, ALLOWED_MIMES, ALLOWED_VIDEO_MIMES, IMAGE_ACCEPT_ATTR, MAX_IMAGE_BYTES, MAX_PDF_BYTES, MAX_VIDEO_BYTES, MEGABYTE, } from "../../../_internal/shared/media/limits.js";
 import { normalizeError } from "../../../errors/normalize.js";
 // Pulls in video-processing libraries most upload sessions never touch —
 // lazy-load rather than bundle into every page rendering a MediaUploadField.
@@ -24,14 +42,35 @@ const VideoTrimModal = dynamic(() => import("../modals/VideoTrimModal.js").then(
 const CLS_PDF_BADGE = "flex h-8 w-8 shrink-0 items-center justify-center rounded-lg bg-error-surface text-error dark:bg-error-surface dark:text-error";
 const CLS_PDF_NAME = "text-[length:var(--appkit-text-sm)] font-medium text-info underline break-all dark:text-info";
 const CLS_PDF_LINK = "text-[length:var(--appkit-text-sm)] underline break-all text-info dark:text-info";
+/*
+ * 🛑 DERIVED from the canonical registry, not restated.
+ *
+ * The `kind` docstring above has always claimed these "auto-derive … from the
+ * canonical media-limits registry". They did not — they were hand-written, and
+ * every one of them was MORE PERMISSIVE than the server, which enforces
+ * `MAX_BYTES[kind]` in BOTH `/api/media/sign` and `/api/media/finalize`. So the
+ * picker accepted work the upload could never complete:
+ *
+ *   image  25 MB  →  server 10 MB
+ *   video 200 MB  →  server 50 MB
+ *   accept "image/*" → matches `image/svg+xml`, which `ALLOWED_IMAGE_MIMES`
+ *                      deliberately excludes as an XSS surface, and which the
+ *                      server 422s only AFTER the crop editor has opened on it
+ *                      (limits.ts's own `IMAGE_ACCEPT_ATTR` docstring).
+ *
+ * Deriving makes the refusal happen in the file picker, where it is a rule,
+ * rather than at the end, where it reads as a failure.
+ */
 const KIND_DEFAULTS = {
-    image: { accept: "image/*", maxSizeMB: 25 },
-    video: { accept: "video/*", maxSizeMB: 200 },
-    pdf: { accept: "application/pdf", maxSizeMB: 10 },
+    image: { accept: IMAGE_ACCEPT_ATTR, maxSizeMB: MAX_IMAGE_BYTES / MEGABYTE },
+    video: { accept: ALLOWED_VIDEO_MIMES.join(","), maxSizeMB: MAX_VIDEO_BYTES / MEGABYTE },
+    pdf: { accept: ALLOWED_DOC_MIMES.join(","), maxSizeMB: MAX_PDF_BYTES / MEGABYTE },
 };
 const AUTO_KIND_DEFAULTS = {
-    accept: "image/*,video/*,application/pdf",
-    maxSizeMB: 200,
+    accept: ALLOWED_MIMES.join(","),
+    // The most permissive of the three, because `auto` genuinely does not know
+    // the kind yet — the per-kind cap is re-checked server-side once it does.
+    maxSizeMB: Math.max(MAX_IMAGE_BYTES, MAX_VIDEO_BYTES, MAX_PDF_BYTES) / MEGABYTE,
 };
 function isVideo(url) {
     return /\.(mp4|webm|ogg|mov|avi)(\?|$)/i.test(url);
@@ -277,14 +316,24 @@ kind, accept: acceptProp, maxSizeMB: maxSizeMBProp, disabled = false, helperText
         setPendingVideoUrl(null);
     };
     const uploadSingleFile = async (file) => {
-        const fileSizeMB = file.size / 1024 / 1024;
+        /*
+         * Bound the pixel dimensions BEFORE the byte check, deliberately.
+         *
+         * The cap is about what we STORE, and a 9 MB phone photo becomes a few
+         * hundred KB here — so checking first would refuse an upload we were about
+         * to make acceptable. Non-images and anything undecodable come back
+         * untouched (see `downscale-image.ts`), so the check below still does its
+         * job for video and PDF.
+         */
+        const prepared = await downscaleImageFile(file);
+        const fileSizeMB = prepared.size / 1024 / 1024;
         if (fileSizeMB > maxSizeMB) {
-            setError(`${file.name}: exceeds ${maxSizeMB}MB limit`);
+            setError(`${prepared.name}: exceeds ${maxSizeMB}MB limit`);
             return null;
         }
-        const url = await onUpload(file);
+        const url = await onUpload(prepared);
         stageUrl(url);
-        return { url, type: file.type };
+        return { url, type: prepared.type };
     };
     /**
      * Client-side first-frame extraction for video uploads. Runs after the
@@ -373,10 +422,17 @@ kind, accept: acceptProp, maxSizeMB: maxSizeMBProp, disabled = false, helperText
         setError(null);
         setIsLoading(true);
         try {
-            const url = await onUpload(file);
-            stageUrl(url);
+            /*
+             * Routed through `uploadSingleFile` rather than calling `onUpload`
+             * directly, which is what this did until 2026-10-19 — so a camera capture
+             * skipped BOTH the `maxSizeMB` check and (once added) the downscale. A
+             * full-sensor capture is precisely the large image both exist for.
+             */
+            const result = await uploadSingleFile(file);
+            if (!result)
+                return;
             const poster = await maybeCaptureVideoPoster(file);
-            afterUpload(url, blob.type || mimeType, poster?.posterUrl, poster?.duration);
+            afterUpload(result.url, result.type, poster?.posterUrl, poster?.duration);
         }
         catch (err) {
             void normalizeError(err);

package/dist/features/media/upload/downscale-image.d.ts

@@ -0,0 +1,56 @@
+/**
+ * downscaleImageFile — bound an image's pixel dimensions and re-encode it
+ * before it ever leaves the browser.
+ *
+ * ## Why this exists
+ *
+ * Until 2026-10-19 the ONLY client-side resize in the whole upload path was
+ * inside `ImageEditor` (`modals/ImageEditor.tsx`), which runs only when the
+ * user opens the crop editor. Everything else stored the original bytes: a 9 MB
+ * phone photo was stored at 9 MB, watermarked at 9 MB, and served at 9 MB into
+ * a 64px thumbnail, because `/api/media/[...slug]` resizes nothing and
+ * `next/image` optimisation was off.
+ *
+ * That is the shape of the cost that suspended this project with HTTP 402 for
+ * Fast Origin Transfer at 5.25x its cap (Root Cause #104). Bounding the master
+ * at upload is the one fix that helps every downstream consumer at once.
+ *
+ * ## Why 2048
+ *
+ * Measured (docs/research/competitor-crawl-2026-10/images.md): worldhobbyshop
+ * serves a 2048x2048 master to photoswipe for zoom, and WordPress's own
+ * `-scaled` threshold is 2560. 2048 survives our lightbox's 300% zoom over a
+ * ~680px display box with detail to spare, and is 1/4 the pixels of a 4096px
+ * phone capture.
+ *
+ * ## Four cases where it deliberately returns the ORIGINAL file
+ *
+ * 1. **Not a raster image we own the pipeline for** — anything outside
+ *    `CONVERTIBLE_MIMES`. SVG is never rasterised (it is also not in
+ *    `ALLOWED_IMAGE_MIMES`), and GIF is never touched because re-encoding an
+ *    animated GIF to a still WebP silently destroys the animation.
+ * 2. **Already small enough AND already a compact format** — re-encoding a
+ *    1200px WebP buys nothing and loses a generation of quality.
+ * 3. **The re-encode came out BIGGER.** A small, already-optimised JPEG can
+ *    grow under WebP q0.9. Shipping the larger file would make this helper a
+ *    pessimisation, so the original wins.
+ * 4. **Anything threw.** 🛑 Fail OPEN. A canvas decode failure, a tainted
+ *    canvas, a browser without `createImageBitmap` — none of those are a reason
+ *    to block a seller's upload. The server still enforces `MAX_BYTES[kind]`,
+ *    so the worst case is the pre-2026-10-19 behaviour, not a hole.
+ */
+/** Longest edge, in CSS pixels, of the stored master. */
+export declare const IMAGE_DOWNSCALE_MAX_EDGE = 2048;
+/** Output MIME for a re-encoded master. */
+export declare const IMAGE_DOWNSCALE_FORMAT = "image/webp";
+/** Output quality for a re-encoded master. */
+export declare const IMAGE_DOWNSCALE_QUALITY = 0.9;
+export interface DownscaleImageOptions {
+    /** Longest edge of the output. Default `IMAGE_DOWNSCALE_MAX_EDGE`. */
+    maxEdge?: number;
+    /** Output MIME. Default `IMAGE_DOWNSCALE_FORMAT`. */
+    format?: string;
+    /** Output quality, 0..1. Default `IMAGE_DOWNSCALE_QUALITY`. */
+    quality?: number;
+}
+export declare function downscaleImageFile(file: File, options?: DownscaleImageOptions): Promise<File>;

package/dist/features/media/upload/downscale-image.js

@@ -0,0 +1,150 @@
+/**
+ * downscaleImageFile — bound an image's pixel dimensions and re-encode it
+ * before it ever leaves the browser.
+ *
+ * ## Why this exists
+ *
+ * Until 2026-10-19 the ONLY client-side resize in the whole upload path was
+ * inside `ImageEditor` (`modals/ImageEditor.tsx`), which runs only when the
+ * user opens the crop editor. Everything else stored the original bytes: a 9 MB
+ * phone photo was stored at 9 MB, watermarked at 9 MB, and served at 9 MB into
+ * a 64px thumbnail, because `/api/media/[...slug]` resizes nothing and
+ * `next/image` optimisation was off.
+ *
+ * That is the shape of the cost that suspended this project with HTTP 402 for
+ * Fast Origin Transfer at 5.25x its cap (Root Cause #104). Bounding the master
+ * at upload is the one fix that helps every downstream consumer at once.
+ *
+ * ## Why 2048
+ *
+ * Measured (docs/research/competitor-crawl-2026-10/images.md): worldhobbyshop
+ * serves a 2048x2048 master to photoswipe for zoom, and WordPress's own
+ * `-scaled` threshold is 2560. 2048 survives our lightbox's 300% zoom over a
+ * ~680px display box with detail to spare, and is 1/4 the pixels of a 4096px
+ * phone capture.
+ *
+ * ## Four cases where it deliberately returns the ORIGINAL file
+ *
+ * 1. **Not a raster image we own the pipeline for** — anything outside
+ *    `CONVERTIBLE_MIMES`. SVG is never rasterised (it is also not in
+ *    `ALLOWED_IMAGE_MIMES`), and GIF is never touched because re-encoding an
+ *    animated GIF to a still WebP silently destroys the animation.
+ * 2. **Already small enough AND already a compact format** — re-encoding a
+ *    1200px WebP buys nothing and loses a generation of quality.
+ * 3. **The re-encode came out BIGGER.** A small, already-optimised JPEG can
+ *    grow under WebP q0.9. Shipping the larger file would make this helper a
+ *    pessimisation, so the original wins.
+ * 4. **Anything threw.** 🛑 Fail OPEN. A canvas decode failure, a tainted
+ *    canvas, a browser without `createImageBitmap` — none of those are a reason
+ *    to block a seller's upload. The server still enforces `MAX_BYTES[kind]`,
+ *    so the worst case is the pre-2026-10-19 behaviour, not a hole.
+ */
+import { normalizeError } from "../../../errors/normalize.js";
+/** Longest edge, in CSS pixels, of the stored master. */
+export const IMAGE_DOWNSCALE_MAX_EDGE = 2048;
+/** Output MIME for a re-encoded master. */
+export const IMAGE_DOWNSCALE_FORMAT = "image/webp";
+/** Output quality for a re-encoded master. */
+export const IMAGE_DOWNSCALE_QUALITY = 0.9;
+/**
+ * MIMEs this helper is willing to decode and re-encode.
+ *
+ * 🛑 Deliberately NOT derived from `ALLOWED_IMAGE_MIMES` — that list is about
+ * what the server will STORE, this one is about what a canvas may safely
+ * round-trip. `image/gif` is in the first and must stay out of the second
+ * (animation loss), and the two lists answering different questions is exactly
+ * why one must not be spelled in terms of the other.
+ */
+const CONVERTIBLE_MIMES = new Set(["image/jpeg", "image/jpg", "image/png", "image/webp"]);
+/** Formats already compact enough that a same-size re-encode is pointless. */
+const ALREADY_COMPACT = new Set(["image/webp", "image/avif"]);
+function replaceExtension(name, mime) {
+    const ext = mime.split("/")[1] || "webp";
+    const dot = name.lastIndexOf(".");
+    const stem = dot > 0 ? name.slice(0, dot) : name;
+    return `${stem}.${ext}`;
+}
+async function decode(file) {
+    if (typeof createImageBitmap === "function") {
+        const bitmap = await createImageBitmap(file);
+        return { width: bitmap.width, height: bitmap.height, source: bitmap, release: () => bitmap.close() };
+    }
+    const url = URL.createObjectURL(file);
+    try {
+        const img = await new Promise((resolve, reject) => {
+            const el = new Image();
+            el.onload = () => resolve(el);
+            el.onerror = () => reject(new Error("image decode failed"));
+            el.src = url;
+        });
+        return {
+            width: img.naturalWidth,
+            height: img.naturalHeight,
+            source: img,
+            release: () => URL.revokeObjectURL(url),
+        };
+    }
+    catch (err) {
+        URL.revokeObjectURL(url);
+        throw err;
+    }
+}
+export async function downscaleImageFile(file, options = {}) {
+    const maxEdge = options.maxEdge ?? IMAGE_DOWNSCALE_MAX_EDGE;
+    const format = options.format ?? IMAGE_DOWNSCALE_FORMAT;
+    const quality = options.quality ?? IMAGE_DOWNSCALE_QUALITY;
+    // Case 1 — not something we are willing to round-trip through a canvas.
+    if (!CONVERTIBLE_MIMES.has(file.type))
+        return file;
+    let decoded = null;
+    try {
+        decoded = await decode(file);
+        const { width, height, source } = decoded;
+        if (!width || !height)
+            return file;
+        const longest = Math.max(width, height);
+        const scale = longest > maxEdge ? maxEdge / longest : 1;
+        // Case 2 — small enough already, and re-encoding would only lose a generation.
+        if (scale === 1 && ALREADY_COMPACT.has(file.type))
+            return file;
+        const targetW = Math.max(1, Math.round(width * scale));
+        const targetH = Math.max(1, Math.round(height * scale));
+        const canvas = document.createElement("canvas");
+        canvas.width = targetW;
+        canvas.height = targetH;
+        const ctx = canvas.getContext("2d");
+        if (!ctx)
+            return file;
+        ctx.imageSmoothingQuality = "high";
+        ctx.drawImage(source, 0, 0, targetW, targetH);
+        const blob = await new Promise((resolve) => canvas.toBlob(resolve, format, quality));
+        if (!blob || blob.size === 0)
+            return file;
+        // Case 3 — the re-encode is bigger than what we started with.
+        if (blob.size >= file.size && scale === 1)
+            return file;
+        return new File([blob], replaceExtension(file.name, format), {
+            type: format,
+            lastModified: file.lastModified,
+        });
+    }
+    catch (err) {
+        void normalizeError(err);
+        /*
+         * Case 4 — fail open. See the header.
+         *
+         * Reported rather than swallowed silently: `normalizeError` fires the
+         * observability hook, so a browser that cannot decode what it just accepted
+         * is visible instead of merely producing a suspiciously large upload. The
+         * upload itself still proceeds, with the original file.
+         *
+         * 🛑 The call sits on the line directly below the `catch` on purpose —
+         * `audit-catch-normalize` only looks a few lines ahead, so putting this
+         * comment first was enough to make it read as an unnormalised catch.
+         */
+        return file;
+    }
+    finally {
+        decoded?.release();
+    }
+}