@mohasinac/appkit 4.52.4 → 4.53.0

package/dist/features/layout/useHoldToOpen.js

@@ -0,0 +1,84 @@
+"use client";
+import { useCallback, useEffect, useRef } from "react";
+/**
+ * How long a press has to last before it counts as "hold to open" rather than
+ * "tap to follow the link". 400ms is the usual long-press threshold — short
+ * enough not to feel like a stall, long enough that an ordinary tap never
+ * trips it.
+ */
+export const HOLD_TO_OPEN_MS = 400;
+/**
+ * useHoldToOpen — press-and-hold a navigation link to open its sub-menu
+ * instead of following it.
+ *
+ * The shared half of the same affordance on two surfaces: the desktop navbar's
+ * dropdown and the mobile bottom nav's sheet. Both wrap a REAL link whose tap
+ * must still navigate, and both need the `click` that a long press still fires
+ * to be swallowed — otherwise the menu opens and the browser immediately
+ * navigates away from it, which reads as the gesture doing nothing.
+ *
+ * 🛑 `held` is a ref, not state. The click handler reads it in the same tick
+ * the timer wrote it, and a state update would not have landed yet — the link
+ * would follow through on every hold.
+ *
+ * @param onHold   called once the press passes the threshold (open the menu)
+ * @param enabled  false for a link with no children — then every handler is a
+ *                 no-op and the link behaves exactly as it did before
+ */
+export function useHoldToOpen(onHold, enabled = true) {
+    const timerRef = useRef(null);
+    const heldRef = useRef(false);
+    const onHoldRef = useRef(onHold);
+    // Keep the callback current without re-creating the handlers (and therefore
+    // without restarting a press in progress on every parent re-render).
+    useEffect(() => {
+        onHoldRef.current = onHold;
+    }, [onHold]);
+    const cancel = useCallback(() => {
+        if (timerRef.current) {
+            clearTimeout(timerRef.current);
+            timerRef.current = null;
+        }
+    }, []);
+    // Clear a pending timer if the item unmounts mid-press — the nav re-renders
+    // its item list whenever the listing-type flags or the session resolve.
+    useEffect(() => cancel, [cancel]);
+    const start = useCallback(() => {
+        heldRef.current = false;
+        cancel();
+        timerRef.current = setTimeout(() => {
+            heldRef.current = true;
+            onHoldRef.current();
+        }, HOLD_TO_OPEN_MS);
+    }, [cancel]);
+    /**
+     * Spread onto the element that wraps (or is) the link. `onClickCapture` is
+     * deliberate rather than `onClick`: on the bottom nav the handlers sit on a
+     * wrapper around `<NavItem>`, and by the time a bubbled click arrives the
+     * anchor's own default is already queued — capture runs before the anchor
+     * sees it, so one set of handlers works whether it is spread onto the link
+     * itself or onto a container.
+     */
+    const handlers = enabled
+        ? {
+            onPointerDown: start,
+            onPointerUp: cancel,
+            onPointerLeave: cancel,
+            onPointerCancel: cancel,
+            onClickCapture: (e) => {
+                if (!heldRef.current)
+                    return;
+                e.preventDefault();
+                e.stopPropagation();
+                heldRef.current = false;
+            },
+            // A long press on touch otherwise raises the OS link callout over the
+            // menu the same gesture just opened.
+            onContextMenu: (e) => {
+                if (heldRef.current)
+                    e.preventDefault();
+            },
+        }
+        : {};
+    return handlers;
+}

package/dist/features/lottery/repository/lottery-entry.repository.d.ts

@@ -1,10 +1,25 @@
 import type { FirebaseSieveFields, FirebaseSieveResult, SieveModel } from "../../../providers/db-firebase";
 import { BaseRepository } from "../../../providers/db-firebase";
-import { type LotteryEntryDocument } from "../schemas/firestore";
+import { type LotteryEntryDocument, type LotteryEntryPlain } from "../schemas/firestore";
 declare class LotteryEntryRepository extends BaseRepository<LotteryEntryDocument> {
     static readonly SIEVE_FIELDS: FirebaseSieveFields;
     constructor();
-    protected mapDoc<D = LotteryEntryDocument>(snap: import("../../../providers/db-firebase").DocumentSnapshot): D;
+    /**
+     * Plaintext PII. **Opt-in and named** — for the admin entries table and the
+     * draw notification, where the real address is the point.
+     */
+    revealEntry(doc: LotteryEntryDocument): LotteryEntryPlain;
+    /** As `revealEntry`, for a list read. */
+    revealEntries(docs: readonly LotteryEntryDocument[]): LotteryEntryPlain[];
+    /**
+     * Masked PII — **the default for any surface that only needs to identify a
+     * row to a human.** Decrypts first, then masks: handing a stored field
+     * straight to `maskName` would return "Anonymous" for every row, because
+     * those helpers refuse ciphertext by design.
+     */
+    maskedEntry(doc: LotteryEntryDocument): LotteryEntryPlain;
+    /** As `maskedEntry`, for a list read. */
+    maskedEntries(docs: readonly LotteryEntryDocument[]): LotteryEntryPlain[];
     /**
      * Get the next sequential userLotteryNumber for a source atomically.
      * Returns current count + 1.
@@ -25,7 +40,7 @@ declare class LotteryEntryRepository extends BaseRepository<LotteryEntryDocument
     /** List entries for a specific user across all sources. */
     listForUser(userId: string, model: SieveModel): Promise<FirebaseSieveResult<LotteryEntryDocument>>;
     /** Create a lottery entry with PII encryption. */
-    createEntry(data: Omit<LotteryEntryDocument, "id">): Promise<LotteryEntryDocument>;
+    createEntry(data: Omit<LotteryEntryPlain, "id">): Promise<LotteryEntryDocument>;
     /** Flag a lottery entry as fraudulent. */
     flagEntry(entryId: string, flagNote: string, flaggedBy: string): Promise<LotteryEntryDocument>;
 }

package/dist/features/lottery/repository/lottery-entry.repository.js

@@ -2,17 +2,48 @@ import { normalizeError } from "../../../errors/normalize.js";
 import { DatabaseError } from "../../../errors/index.js";
 import { serverLogger } from "../../../monitoring/index.js";
 import { BaseRepository, prepareForFirestore, parseSieveDateValue, } from "../../../providers/db-firebase/index.js";
-import { decryptPiiFields, encryptPiiFields, LOTTERY_ENTRY_PII_FIELDS, } from "../../../security/index.js";
+import { encryptPiiFields, maskPii, revealPii, LOTTERY_ENTRY_PII_FIELDS, } from "../../../security/index.js";
 import { LOTTERY_ENTRIES_COLLECTION, LOTTERY_ENTRY_FIELDS, } from "../schemas/firestore.js";
 class LotteryEntryRepository extends BaseRepository {
     constructor() {
         super(LOTTERY_ENTRIES_COLLECTION);
     }
-    mapDoc(snap) {
-        const raw = super.mapDoc(snap);
-        return decryptPiiFields(raw, [
-            ...LOTTERY_ENTRY_PII_FIELDS,
-        ]);
+    /*
+     * 🛑 `mapDoc` is NOT overridden, and that is the whole change.
+     *
+     * It used to call `decryptPiiFields` on every read, so ciphertext never left
+     * the database and all five consumers handled plaintext without ever saying
+     * so. Following `SiteSettingsRepository`: reads return what Firestore holds,
+     * and plaintext requires one of the two named methods below.
+     *
+     * The compiler enforces it rather than a convention doing so —
+     * `LotteryEntryDocument`'s PII fields are `Encrypted<string>`, assignable to
+     * nothing that wants a plain `string`, so a reader that skips both accessors
+     * is a compile error naming the file and line.
+     */
+    /**
+     * Plaintext PII. **Opt-in and named** — for the admin entries table and the
+     * draw notification, where the real address is the point.
+     */
+    revealEntry(doc) {
+        return revealPii(doc, LOTTERY_ENTRY_PII_FIELDS);
+    }
+    /** As `revealEntry`, for a list read. */
+    revealEntries(docs) {
+        return docs.map((d) => this.revealEntry(d));
+    }
+    /**
+     * Masked PII — **the default for any surface that only needs to identify a
+     * row to a human.** Decrypts first, then masks: handing a stored field
+     * straight to `maskName` would return "Anonymous" for every row, because
+     * those helpers refuse ciphertext by design.
+     */
+    maskedEntry(doc) {
+        return maskPii(doc, LOTTERY_ENTRY_PII_FIELDS);
+    }
+    /** As `maskedEntry`, for a list read. */
+    maskedEntries(docs) {
+        return docs.map((d) => this.maskedEntry(d));
     }
     /**
      * Get the next sequential userLotteryNumber for a source atomically.
@@ -78,6 +109,17 @@ class LotteryEntryRepository extends BaseRepository {
         });
     }
     /** Create a lottery entry with PII encryption. */
+    /*
+     * 🛑 Takes PLAINTEXT (`LotteryEntryPlain`), returns CIPHERTEXT
+     * (`LotteryEntryDocument`), and the asymmetry is the point.
+     *
+     * The caller holds a real email and phone; this method encrypts them. Typing
+     * the parameter `Omit<LotteryEntryDocument, "id">` would have demanded the
+     * caller hand over `Encrypted<string>` it does not have, and the only way to
+     * satisfy that is `asEncrypted(email)` — which labels plaintext as ciphertext
+     * and is exactly the misuse `asEncrypted`'s own docstring forbids. The
+     * encryption happens here; so does the type change.
+     */
     async createEntry(data) {
         try {
             const encrypted = encryptPiiFields(data, [...LOTTERY_ENTRY_PII_FIELDS]);

package/dist/features/lottery/schemas/firestore.d.ts

@@ -2,7 +2,23 @@
  * LotteryEntry Firestore Document Type & Constants
  */
 import type { LotteryEntryStatus } from "../types";
+import type { Encrypted, Plaintext } from "../../../security/encrypted";
 export declare const LOTTERY_ENTRIES_COLLECTION: "lotteryEntries";
+/**
+ * The same entry with its PII as plain `string` — what the two named
+ * repository accessors return.
+ *
+ * 🛑 Derived with a mapped type, never hand-written. A second literal listing
+ * the same ~18 fields would drift the first time one was added to only one of
+ * them, and the drift is invisible: both compile, and the one nobody updated
+ * silently drops the new field from every reveal/mask call site.
+ *
+ * It is deliberately NOT distinguishable from a MASKED entry. `maskPii` also
+ * returns plain strings, and a type cannot express "these characters are
+ * asterisks" — the distinction lives in WHICH named method you called, which
+ * is why they are two methods rather than one taking a boolean.
+ */
+export type LotteryEntryPlain = Plaintext<LotteryEntryDocument>;
 export type LotteryEntryDocument = {
     id: string;
     sourceType: "event" | "product";
@@ -11,11 +27,23 @@ export type LotteryEntryDocument = {
     /** Set when sourceType === "product" */
     productId?: string;
     userId: string;
-    userDisplayName?: string;
-    /** PII — encrypted at rest */
-    userEmail?: string;
-    /** PII — encrypted at rest; required */
-    userPhone: string;
+    /**
+     * PII — CIPHERTEXT as it sits here.
+     *
+     * 🛑 `Encrypted<string>` is a promise about the VALUE, kept by
+     * `LotteryEntryRepository` no longer decrypting in `mapDoc`. Branding a field
+     * that is still decrypted on read asserts something false, and `decryptValue`
+     * passes a non-`enc:v1:` string straight through — so the lie would silently
+     * "work" and surface only on the rows that were genuinely encrypted.
+     *
+     * Readers call `lotteryEntryRepository.maskedEntry(doc)` (the UI default) or
+     * `revealEntry(doc)` (opt-in, named, greppable).
+     */
+    userDisplayName?: Encrypted<string>;
+    /** PII — ciphertext at rest; see `userDisplayName` */
+    userEmail?: Encrypted<string>;
+    /** PII — ciphertext at rest; required. See `userDisplayName` */
+    userPhone: Encrypted<string>;
     /** User-provided external payment TX ID */
     transactionId: string;
     /** User-provided time of payment */

package/dist/features/loyalty/api/balance/route.js

@@ -24,7 +24,7 @@ export async function GET(request) {
         const repo = db.getRepository("loyalty_balance");
         const result = await repo.findAll({
             filters: `userId==${userId}`,
-            perPage: 1,
+            pageSize: 1,
         });
         return NextResponse.json({
             success: true,

package/dist/features/loyalty/api/history/route.js

@@ -33,7 +33,7 @@ export async function GET(request) {
             filters: `userId==${userId}`,
             sort: "-createdAt",
             page,
-            perPage: pageSize,
+            pageSize: pageSize,
         });
         const totalPages = Math.max(1, Math.ceil(result.total / pageSize));
         return NextResponse.json({

package/dist/features/media/MediaImage.js

@@ -89,7 +89,6 @@ export function MediaImage({ src, alt, size = "card", priority = false, loading,
                 retryTimeoutRef.current = null;
             }
         };
-        // eslint-disable-next-line react-hooks/exhaustive-deps
     }, [resolvedSrc]);
     const wrapperExtra = [
         rounded ? ROUNDED_MAP[rounded] : "",

package/dist/features/media/MediaPickerModal.js

@@ -11,7 +11,13 @@ import { Row, Stack } from "../../ui/components/Layout.js";
 import { Alert } from "../../ui/components/Alert.js";
 import { MediaImage } from "./MediaImage.js";
 import { MediaUploadField } from "./upload/MediaUploadField.js";
-import { useMediaUpload, useMediaCleanup } from "./index.js";
+/*
+ * The DEFINING module, not `./index` — Root Cause #18. The barrel re-exports
+ * this very component, so importing back through it made a two-module import
+ * cycle (`audit-import-cycles` component 4), and a cycle makes "which module
+ * owns this symbol" unanswerable for every tool that walks the graph.
+ */
+import { useMediaUpload, useMediaCleanup } from "./hooks/useMedia.js";
 import { ADMIN_ENDPOINTS } from "../../constants/api-endpoints.js";
 const MEDIA_LIST_ENDPOINT = ADMIN_ENDPOINTS.MEDIA_LIST;
 const EXISTING_GRID_MAX_HEIGHT = "max-h-96";

package/dist/features/media/modals/ImageEditor.js

@@ -9,6 +9,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useState, useRef, useCallback } from "react";
 import { useTranslations } from "next-intl";
 import { Cropper } from "react-advanced-cropper";
+import { IMAGE_DOWNSCALE_FORMAT, IMAGE_DOWNSCALE_MAX_EDGE, IMAGE_DOWNSCALE_QUALITY, } from "../upload/downscale-image.js";
 /*
  * 🛑 NO `import "react-advanced-cropper/dist/style.css"` HERE.
  *
@@ -27,7 +28,10 @@ import { Cropper } from "react-advanced-cropper";
  */
 import { Button, Div, Modal, Row, Stack, Text, useToast } from "../../../ui/index.js";
 import { normalizeError } from "../../../errors/normalize.js";
-export function ImageEditor({ isOpen, imageUrl, onClose, onSave, aspectRatio, outputFormat = "image/webp", outputQuality = 0.9, maxOutputWidth = 2048, }) {
+export function ImageEditor({ isOpen, imageUrl, onClose, onSave, aspectRatio, 
+// Shared with the always-on upload downscaler so the crop path and the
+// non-crop path cannot produce differently-sized masters.
+outputFormat = IMAGE_DOWNSCALE_FORMAT, outputQuality = IMAGE_DOWNSCALE_QUALITY, maxOutputWidth = IMAGE_DOWNSCALE_MAX_EDGE, }) {
     const t = useTranslations("mediaEditor");
     const { showToast } = useToast();
     const cropperRef = useRef(null);

package/dist/features/media/modals/VideoThumbnailSelector.js

@@ -8,7 +8,23 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
  */
 import { useState, useRef } from "react";
 import { useTranslations } from "next-intl";
-import { Alert, Button, Div, Modal, 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 { Button } from "../../../ui/components/Button.js";
+import { Div } from "../../../ui/components/Div.js";
+import { Row, Stack } from "../../../ui/components/Layout.js";
+import { Modal } from "../../../ui/components/Modal.js";
+import { Spinner } from "../../../ui/components/Spinner.js";
+import { Span, Text } from "../../../ui/components/Typography.js";
 import { normalizeError } from "../../../errors/normalize.js";
 import { toUserMessage } from "../../../errors/error-display-map.js";
 const __O = {

package/dist/features/media/repository/media-assets.repository.d.ts

@@ -21,6 +21,25 @@ export interface MediaAssetDocument {
      * any other upload without parsing filename strings.
      */
     contextType?: string;
+    /**
+     * When the watermark was composited INTO the stored bytes, at upload time.
+     *
+     * 🛑 Absent means "legacy" and is the load-bearing default. Until 2026-10-19
+     * `/api/media/[...slug]` sharp-decoded, composited and re-encoded EVERY image
+     * response — the cost profile behind the HTTP 402 Fast Origin Transfer
+     * suspension (Root Cause #104). Now `/api/media/finalize` bakes the mark once
+     * and stamps this field, and the proxy skips the composite when it is set.
+     *
+     * So an asset uploaded before this existed has no field, the proxy watermarks
+     * it on read exactly as it always did, and **no backfill is required** for the
+     * 504 rows that predate it. A backfill can run later via the Async Job
+     * Primitive, or never.
+     *
+     * It is written in the SAME operation that stores the watermarked bytes, so a
+     * row can never claim a mark the object does not carry — which would show an
+     * unwatermarked image, or double-watermark it the other way round.
+     */
+    watermarkedAt?: Date;
     createdAt: Date;
 }
 export type MediaAssetCreateInput = Omit<MediaAssetDocument, "id" | "createdAt">;

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>;