@mohasinac/appkit 4.10.0 → 4.11.0

package/dist/features/media/MediaImage.js

@@ -1,7 +1,7 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import Image from "next/image";
-import { useState } from "react";
+import { useEffect, useRef, useState } from "react";
 import { Div, Row, Span } from "../../ui";
 import { ROUNDED_MAP, SHADOW_MAP } from "../../ui/components/surface-tokens";
 import { resolveMediaUrl } from "../../utils/media-url";
@@ -25,6 +25,13 @@ const FALLBACK_ICONS = {
     gallery: "📦",
     avatar: "👤",
 };
+// A freshly-uploaded media slug can legitimately 404 for a brief window
+// right after upload — the Firestore doc write and the Storage object write
+// don't land atomically (see src/app/api/media/[...slug]/route.ts's own
+// comment on this race). Retry with backoff before latching the fallback
+// icon, instead of failing permanently on the very first request.
+const MAX_LOAD_RETRIES = 3;
+const RETRY_BACKOFF_MS = [600, 1200, 2400];
 /** Resolve every URL in a comma-separated srcset string through the media proxy. */
 function resolveSrcSet(input) {
     return input
@@ -44,15 +51,39 @@ function resolveSrcSet(input) {
 export function MediaImage({ src, alt, size = "card", priority = false, loading, objectFit = "cover", fallback, className, rounded, shadow, style, sources, onError, }) {
     const [hasError, setHasError] = useState(false);
     const [isLoaded, setIsLoaded] = useState(false);
+    const [retryCount, setRetryCount] = useState(0);
+    const retryTimeoutRef = useRef(null);
     const icon = fallback ?? FALLBACK_ICONS[size];
     const fitClass = objectFit === "contain" ? "object-contain" : "object-cover";
     const resolvedSrc = resolveMediaUrl(src);
+    // Reset error/load/retry state whenever the resolved src actually changes.
+    // Without this, a component instance that hit a load failure once (e.g.
+    // lost the post-upload propagation race above) latches hasError forever,
+    // even across a later prop change to a src that would now succeed.
+    useEffect(() => {
+        setHasError(false);
+        setIsLoaded(false);
+        setRetryCount(0);
+        return () => {
+            if (retryTimeoutRef.current) {
+                clearTimeout(retryTimeoutRef.current);
+                retryTimeoutRef.current = null;
+            }
+        };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [resolvedSrc]);
     const wrapperExtra = [
         rounded ? ROUNDED_MAP[rounded] : "",
         shadow ? SHADOW_MAP[shadow] : "",
         className ?? "",
     ].filter(Boolean).join(" ");
     const handleError = () => {
+        if (retryCount < MAX_LOAD_RETRIES) {
+            retryTimeoutRef.current = setTimeout(() => {
+                setRetryCount((count) => count + 1);
+            }, RETRY_BACKOFF_MS[retryCount]);
+            return;
+        }
         setHasError(true);
         onError?.();
     };
@@ -62,15 +93,20 @@ export function MediaImage({ src, alt, size = "card", priority = false, loading,
     const isSvg = resolvedSrc.toLowerCase().endsWith(".svg") ||
         resolvedSrc.includes("image/svg") ||
         /[./]svg(\?|$)/i.test(resolvedSrc);
+    // Cache-bust the retried request so a browser-cached 404 response isn't
+    // silently re-served — the underlying URL is otherwise byte-identical.
+    const requestSrc = retryCount > 0
+        ? `${resolvedSrc}${resolvedSrc.includes("?") ? "&" : "?"}retry=${retryCount}`
+        : resolvedSrc;
     // Art-directed `<picture>` path — bypasses Next.js `<Image>` because the
     // browser must pick the matching `<source>` itself. Loading + decoding hints
     // come from the consumer's preset.
     if (sources && sources.length > 0) {
-        return (_jsxs(Div, { className: `relative w-full h-full overflow-hidden${wrapperExtra ? ` ${wrapperExtra}` : ""}`, style: style, children: [!isLoaded && (_jsx(Div, { className: "absolute inset-0 animate-pulse", surface: "subtle", "aria-hidden": "true" })), _jsxs("picture", { children: [sources.map((source, index) => (_jsx("source", { srcSet: resolveSrcSet(source.srcSet), type: source.type, media: source.media }, `${source.media ?? ""}-${source.type ?? ""}-${index}`))), _jsx("img", { src: resolvedSrc, alt: alt, loading: loading ?? (priority ? "eager" : "lazy"), decoding: "async", 
+        return (_jsxs(Div, { className: `relative w-full h-full overflow-hidden${wrapperExtra ? ` ${wrapperExtra}` : ""}`, style: style, children: [!isLoaded && (_jsx(Div, { className: "absolute inset-0 animate-pulse", surface: "subtle", "aria-hidden": "true" })), _jsxs("picture", { children: [sources.map((source, index) => (_jsx("source", { srcSet: resolveSrcSet(source.srcSet), type: source.type, media: source.media }, `${source.media ?? ""}-${source.type ?? ""}-${index}`))), _jsx("img", { src: requestSrc, alt: alt, loading: loading ?? (priority ? "eager" : "lazy"), decoding: "async", 
                             // catalogued primitive for media (variant catalogue allows the inner
                             // <img> here). Object-fit + className come from typed props.
                             className: `absolute inset-0 w-full h-full ${fitClass}`, onLoad: () => setIsLoaded(true), onError: handleError })] })] }));
     }
-    return (_jsxs(Div, { className: `relative w-full h-full overflow-hidden${wrapperExtra ? ` ${wrapperExtra}` : ""}`, style: style, children: [!isLoaded && (_jsx(Div, { className: "absolute inset-0 animate-pulse", surface: "subtle", "aria-hidden": "true" })), _jsx(Image, { src: resolvedSrc, alt: alt, fill: true, priority: priority, loading: loading ?? (priority ? "eager" : "lazy"), className: fitClass, sizes: SIZE_HINTS[size], onLoad: () => setIsLoaded(true), onError: () => setHasError(true), unoptimized: isSvg })] }));
+    return (_jsxs(Div, { className: `relative w-full h-full overflow-hidden${wrapperExtra ? ` ${wrapperExtra}` : ""}`, style: style, children: [!isLoaded && (_jsx(Div, { className: "absolute inset-0 animate-pulse", surface: "subtle", "aria-hidden": "true" })), _jsx(Image, { src: requestSrc, alt: alt, fill: true, priority: priority, loading: loading ?? (priority ? "eager" : "lazy"), className: fitClass, sizes: SIZE_HINTS[size], onLoad: () => setIsLoaded(true), onError: handleError, unoptimized: isSvg })] }));
 }
 export default MediaImage;

package/dist/features/media/types/index.d.ts

@@ -12,6 +12,13 @@ export interface MediaField {
     source?: MediaSource;
     /** YouTube video ID. Only set when source === "youtube". */
     youtubeId?: string;
+    /**
+     * Duration in seconds, for `type: "video"`. Captured automatically for
+     * direct uploads (off-DOM `<video>` element, see `video-poster.ts`) — not
+     * obtainable client-side for `source: "youtube" | "external"` without a
+     * server round-trip, so it stays undefined for those sources.
+     */
+    duration?: number;
 }
 export declare const mediaFieldSchema: z.ZodObject<{
     url: z.ZodString;
@@ -20,6 +27,7 @@ export declare const mediaFieldSchema: z.ZodObject<{
     thumbnailUrl: z.ZodOptional<z.ZodString>;
     source: z.ZodOptional<z.ZodEnum<["upload", "youtube", "external"]>>;
     youtubeId: z.ZodOptional<z.ZodString>;
+    duration: z.ZodOptional<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
     type: "video" | "image" | "file";
     url: string;
@@ -27,6 +35,7 @@ export declare const mediaFieldSchema: z.ZodObject<{
     alt?: string | undefined;
     thumbnailUrl?: string | undefined;
     youtubeId?: string | undefined;
+    duration?: number | undefined;
 }, {
     type: "video" | "image" | "file";
     url: string;
@@ -34,6 +43,7 @@ export declare const mediaFieldSchema: z.ZodObject<{
     alt?: string | undefined;
     thumbnailUrl?: string | undefined;
     youtubeId?: string | undefined;
+    duration?: number | undefined;
 }>;
 export declare function coerceMediaField(value: MediaFieldInput, fallbackType?: MediaFieldType): MediaField | null;
 export declare function coerceMediaFieldArray(values: Array<MediaField | string> | null | undefined, fallbackType?: MediaFieldType): MediaField[];

package/dist/features/media/types/index.js

@@ -7,6 +7,7 @@ export const mediaFieldSchema = z.object({
     thumbnailUrl: z.string().optional(),
     source: z.enum(["upload", "youtube", "external"]).optional(),
     youtubeId: z.string().optional(),
+    duration: z.number().optional(),
 });
 export function coerceMediaField(value, fallbackType = "image") {
     if (!value) {

package/dist/features/media/upload/MediaUploadField.d.ts

@@ -28,6 +28,12 @@ export interface MediaUploadFieldProps {
     enableTrim?: boolean;
     enableThumbnail?: boolean;
     onThumbnailChange?: (url: string) => void;
+    /**
+     * Fired with the captured duration (seconds) for a direct video upload —
+     * mirrors `onThumbnailChange`. Never fires for the YouTube/External-URL
+     * tabs (no client-side way to read those without a server round-trip).
+     */
+    onDurationChange?: (duration: number) => void;
     /** Show a "YouTube URL" tab to embed a YouTube video by ID or URL. */
     showYoutube?: boolean;
     /** Show an "External URL" tab to link a third-party image/video URL. */
@@ -63,4 +69,4 @@ export interface MediaUploadFieldProps {
      */
     autoCapturePoster?: boolean;
 }
-export declare function MediaUploadField({ label, value, onChange, onChangeField, onUpload, kind, accept: acceptProp, maxSizeMB: maxSizeMBProp, disabled, helperText, captureSource, captureMode, enableTrim, enableThumbnail, onThumbnailChange, showYoutube, showExternal, onAbort, onStagedUrlsChange, isPersisted, multiple, onAddUrl, autoCapturePoster, }: MediaUploadFieldProps): import("react").JSX.Element;
+export declare function MediaUploadField({ label, value, onChange, onChangeField, onUpload, kind, accept: acceptProp, maxSizeMB: maxSizeMBProp, disabled, helperText, captureSource, captureMode, enableTrim, enableThumbnail, onThumbnailChange, onDurationChange, showYoutube, showExternal, onAbort, onStagedUrlsChange, isPersisted, multiple, onAddUrl, autoCapturePoster, }: MediaUploadFieldProps): import("react").JSX.Element;

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

@@ -88,7 +88,7 @@ export function MediaUploadField({ label, value, onChange, onChangeField, onUplo
 // SB-UNI-Z5 2026-05-13 — `kind` derives accept/maxSizeMB when not set
 // explicitly; explicit props still win. "*" + 50 stay as the floor for
 // back-compat with callers that pass neither.
-kind, accept: acceptProp, maxSizeMB: maxSizeMBProp, disabled = false, helperText, captureSource = "both", captureMode = "photo", enableTrim = true, enableThumbnail = true, onThumbnailChange, showYoutube = true, showExternal = true, onAbort, onStagedUrlsChange, isPersisted = false, multiple = false, onAddUrl, autoCapturePoster = true, }) {
+kind, accept: acceptProp, maxSizeMB: maxSizeMBProp, disabled = false, helperText, captureSource = "both", captureMode = "photo", enableTrim = true, enableThumbnail = true, onThumbnailChange, onDurationChange, showYoutube = true, showExternal = true, onAbort, onStagedUrlsChange, isPersisted = false, multiple = false, onAddUrl, autoCapturePoster = true, }) {
     const [isLoading, setIsLoading] = useState(false);
     const [error, setError] = useState(null);
     const [pendingVideoUrl, setPendingVideoUrl] = useState(null);
@@ -198,14 +198,18 @@ kind, accept: acceptProp, maxSizeMB: maxSizeMBProp, disabled = false, helperText
         : captureMode === "both"
             ? "image/*,video/*"
             : "image/*";
-    const afterUpload = (url, fileType, autoPosterUrl) => {
+    const afterUpload = (url, fileType, autoPosterUrl, duration) => {
         onChangeField?.({
             url,
             type: inferMediaTypeFromMime(fileType, url),
+            source: "upload",
             ...(autoPosterUrl ? { thumbnailUrl: autoPosterUrl } : {}),
+            ...(duration ? { duration } : {}),
         });
         if (autoPosterUrl)
             onThumbnailChange?.(autoPosterUrl);
+        if (duration)
+            onDurationChange?.(duration);
         const isVideoFile = fileType.startsWith("video/");
         if (isVideoFile && enableTrim) {
             setPendingVideoUrl(url);
@@ -283,7 +287,7 @@ kind, accept: acceptProp, maxSizeMB: maxSizeMBProp, disabled = false, helperText
             const posterFile = posterBlobAsFile(poster, file.name);
             const posterUrl = await onUpload(posterFile);
             stageUrl(posterUrl);
-            return posterUrl;
+            return { posterUrl, duration: poster.duration };
         }
         catch (err) {
             // The upload-poster step is best-effort. Log via normalizeError so any
@@ -309,8 +313,8 @@ kind, accept: acceptProp, maxSizeMB: maxSizeMBProp, disabled = false, helperText
             else {
                 const result = await uploadSingleFile(files[0]);
                 if (result) {
-                    const posterUrl = (await maybeCaptureVideoPoster(files[0])) ?? undefined;
-                    afterUpload(result.url, result.type, posterUrl);
+                    const poster = await maybeCaptureVideoPoster(files[0]);
+                    afterUpload(result.url, result.type, poster?.posterUrl, poster?.duration);
                 }
             }
         }
@@ -353,8 +357,8 @@ kind, accept: acceptProp, maxSizeMB: maxSizeMBProp, disabled = false, helperText
         try {
             const url = await onUpload(file);
             stageUrl(url);
-            const posterUrl = (await maybeCaptureVideoPoster(file)) ?? undefined;
-            afterUpload(url, blob.type || mimeType, posterUrl);
+            const poster = await maybeCaptureVideoPoster(file);
+            afterUpload(url, blob.type || mimeType, poster?.posterUrl, poster?.duration);
         }
         catch (err) {
             void normalizeError(err);

package/dist/features/media/upload/video-poster.d.ts

@@ -26,6 +26,8 @@ export interface ExtractedPoster {
     /** Frame dimensions in pixels (also the JPEG's pixel dimensions). */
     width: number;
     height: number;
+    /** Video duration in seconds, read from the same off-DOM element. */
+    duration: number;
 }
 /**
  * Build a deterministic filename for the captured poster. We mirror the

package/dist/features/media/upload/video-poster.js

@@ -25,6 +25,20 @@ const TARGET_FRAME_TIME_SECONDS = 0.5;
 const JPEG_QUALITY = 0.85;
 const LOAD_TIMEOUT_MS = 10000;
 const POSTER_MIME = "image/jpeg";
+/** Bounded wait for `video.duration` to become a finite, positive number. */
+async function readDuration(video) {
+    if (Number.isFinite(video.duration) && video.duration > 0)
+        return video.duration;
+    return new Promise((resolve) => {
+        const timer = window.setTimeout(() => resolve(0), 2000);
+        video.addEventListener("durationchange", () => {
+            if (Number.isFinite(video.duration) && video.duration > 0) {
+                window.clearTimeout(timer);
+                resolve(video.duration);
+            }
+        }, { once: true });
+    });
+}
 /**
  * Build a deterministic filename for the captured poster. We mirror the
  * source video's basename so downstream code can correlate the two assets
@@ -86,6 +100,7 @@ export async function extractVideoPosterFrame(file) {
         const height = video.videoHeight;
         if (!width || !height)
             return null;
+        const duration = await readDuration(video);
         const canvas = document.createElement("canvas");
         canvas.width = width;
         canvas.height = height;
@@ -96,7 +111,7 @@ export async function extractVideoPosterFrame(file) {
         const blob = await new Promise((resolve) => canvas.toBlob(resolve, POSTER_MIME, JPEG_QUALITY));
         if (!blob)
             return null;
-        return { blob, width, height };
+        return { blob, width, height, duration };
     }
     catch (_err) {
         void normalizeError(_err);

package/dist/features/media/upload/video-poster.test.js

@@ -19,7 +19,7 @@ describe("posterBlobAsFile", () => {
         const blob = new Blob([new Uint8Array([0xff, 0xd8, 0xff])], {
             type: "image/jpeg",
         });
-        const file = posterBlobAsFile({ blob, width: 320, height: 180 }, "promo-reel.mp4");
+        const file = posterBlobAsFile({ blob, width: 320, height: 180, duration: 12.5 }, "promo-reel.mp4");
         expect(file).toBeInstanceOf(File);
         expect(file.name).toBe("promo-reel.poster.jpg");
         expect(file.type).toBe("image/jpeg");

package/dist/features/orders/components/OrderStatusTimeline.d.ts

@@ -0,0 +1,12 @@
+export interface OrderStatusTimelineProps {
+    orderStatus: string;
+    orderDate?: string;
+    shippingDate?: string;
+    deliveryDate?: string;
+    cancellationDate?: string;
+    trackingNumber?: string;
+    shippingCarrier?: string;
+    trackingUrl?: string;
+    className?: string;
+}
+export declare function OrderStatusTimeline({ orderStatus, orderDate, shippingDate, deliveryDate, cancellationDate, trackingNumber, shippingCarrier, trackingUrl, className, }: OrderStatusTimelineProps): import("react").JSX.Element;

package/dist/features/orders/components/OrderStatusTimeline.js

@@ -0,0 +1,55 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * OrderStatusTimeline — a genuine (not fabricated/estimated) status timeline
+ * built from the real per-status timestamps already written by the
+ * order-status-update path (`orderDate`/`shippingDate`/`deliveryDate`/
+ * `cancellationDate`). No live courier-API integration — `trackingUrl` is
+ * just the passthrough link a seller/admin entered, rendered as an external
+ * link that opens in a new tab. Statuses with no dedicated date field
+ * (confirmed/processing/return_requested/returned/refunded) render as a step
+ * without a timestamp rather than showing a made-up date.
+ */
+import { Anchor, Badge, Div, Heading, Row, Stack, Text } from "../../../ui";
+const STAGE_SEQUENCE = ["pending", "confirmed", "processing", "shipped", "delivered"];
+const STAGE_LABELS = {
+    pending: "Order placed",
+    confirmed: "Confirmed",
+    processing: "Processing",
+    shipped: "Shipped",
+    delivered: "Delivered",
+    cancelled: "Cancelled",
+    return_requested: "Return requested",
+    returned: "Returned",
+    refunded: "Refunded",
+};
+function buildSteps(props) {
+    const status = (props.orderStatus ?? "").toLowerCase();
+    const currentIndex = STAGE_SEQUENCE.indexOf(status);
+    const steps = [{ key: "pending", label: STAGE_LABELS.pending, date: props.orderDate }];
+    if ((status === "confirmed" || status === "processing") && !props.shippingDate) {
+        steps.push({ key: status, label: STAGE_LABELS[status] });
+    }
+    if (props.shippingDate || currentIndex >= 3) {
+        steps.push({ key: "shipped", label: STAGE_LABELS.shipped, date: props.shippingDate });
+    }
+    if (props.deliveryDate || status === "delivered") {
+        steps.push({ key: "delivered", label: STAGE_LABELS.delivered, date: props.deliveryDate });
+    }
+    if (status === "cancelled" || props.cancellationDate) {
+        steps.push({ key: "cancelled", label: STAGE_LABELS.cancelled, date: props.cancellationDate });
+    }
+    else if (status === "return_requested" || status === "returned" || status === "refunded") {
+        steps.push({ key: status, label: STAGE_LABELS[status] ?? status });
+    }
+    return steps;
+}
+export function OrderStatusTimeline({ orderStatus, orderDate, shippingDate, deliveryDate, cancellationDate, trackingNumber, shippingCarrier, trackingUrl, className = "", }) {
+    const steps = buildSteps({ orderStatus, orderDate, shippingDate, deliveryDate, cancellationDate });
+    const isTerminalNegative = steps[steps.length - 1]?.key === "cancelled";
+    return (_jsxs(Div, { className: className, rounded: "xl", padding: "md", surface: "muted", border: "default", children: [_jsx(Heading, { level: 3, size: "sm", weight: "semibold", color: "muted", className: "mb-3", children: "Tracking" }), _jsx(Stack, { gap: "none", children: steps.map((step, i) => {
+                    const isLast = i === steps.length - 1;
+                    const isNegative = step.key === "cancelled";
+                    return (_jsxs(Row, { gap: "sm", padding: isLast ? "none" : "b-md", children: [_jsxs(Stack, { gap: "none", align: "center", className: "shrink-0", children: [_jsx(Div, { className: `h-2.5 w-2.5 ${isNegative ? "" : "bg-[var(--appkit-color-primary)]"}`, rounded: "full", surface: isNegative ? "danger-surface" : "none" }), !isLast && _jsx(Div, { className: "w-px flex-1 min-h-[24px]", surface: "subtle" })] }), _jsxs(Stack, { gap: "none", className: "min-w-0 flex-1", children: [_jsx(Text, { size: "sm", weight: "medium", className: isNegative ? "text-error" : undefined, children: step.label }), _jsx(Text, { size: "xs", color: "muted", children: step.date ? new Date(step.date).toLocaleString() : "—" })] })] }, step.key));
+                }) }), (trackingNumber || shippingCarrier || trackingUrl) && !isTerminalNegative && (_jsx(Div, { className: "mt-3 border-t border-[var(--appkit-color-border)]", padding: "t-sm", children: _jsxs(Stack, { gap: "xs", children: [shippingCarrier && (_jsxs(Row, { justify: "between", children: [_jsx(Text, { size: "sm", color: "muted", children: "Carrier" }), _jsx(Text, { size: "sm", weight: "medium", children: shippingCarrier })] })), trackingNumber && (_jsxs(Row, { justify: "between", children: [_jsx(Text, { size: "sm", color: "muted", children: "Tracking number" }), _jsx(Text, { size: "sm", weight: "medium", children: trackingNumber })] })), trackingUrl && (_jsx(Row, { justify: "end", children: _jsx(Anchor, { href: trackingUrl, tone: "brand", weight: "semibold", size: "sm", children: "Track with carrier \u2192" }) }))] }) })), !trackingNumber && !trackingUrl && !isTerminalNegative && (_jsx(Badge, { variant: "default", className: "mt-3", children: "No tracking details yet" }))] }));
+}

package/dist/features/orders/components/index.d.ts

@@ -6,6 +6,8 @@ export { OrderSiblingPayments } from "./OrderSiblingPayments";
 export type { OrderSiblingPaymentsProps } from "./OrderSiblingPayments";
 export { OrderPaymentSummary } from "./OrderPaymentSummary";
 export type { OrderPaymentSummaryProps } from "./OrderPaymentSummary";
+export { OrderStatusTimeline } from "./OrderStatusTimeline";
+export type { OrderStatusTimelineProps } from "./OrderStatusTimeline";
 export { RefundHistoryTable } from "./RefundHistoryTable";
 export type { RefundHistoryTableProps } from "./RefundHistoryTable";
 export { RefundRequestView } from "./RefundRequestView";

package/dist/features/orders/components/index.js

@@ -3,5 +3,6 @@ export { MarketplaceOrderCard, } from "./MarketplaceOrderCard";
 export { OrderFilters, ORDER_FILTER_KEYS, ORDER_ADMIN_SORT_OPTIONS, ORDER_SELLER_SORT_OPTIONS, ORDER_USER_SORT_OPTIONS, getOrderFilterKeys, getOrderSortOptions, } from "./OrderFilters";
 export { OrderSiblingPayments } from "./OrderSiblingPayments";
 export { OrderPaymentSummary } from "./OrderPaymentSummary";
+export { OrderStatusTimeline } from "./OrderStatusTimeline";
 export { RefundHistoryTable } from "./RefundHistoryTable";
 export { RefundRequestView } from "./RefundRequestView";

package/dist/features/orders/constants/payment-window.d.ts

@@ -8,3 +8,28 @@ export declare const PAYMENT_WINDOW_MS: number;
 /** Cancellation reasons this feature writes to `OrderDocument.cancellationReason` (a free-form string field). */
 export declare const PAYMENT_WINDOW_EXPIRED_REASON = "payment_window_expired";
 export declare const PAYMENT_FRAUD_REJECTED_REASON = "payment_fraud_rejected";
+/**
+ * The `paymentMethod` values that settle out-of-band and therefore require a
+ * buyer-uploaded proof + a human review pass. Single source of truth for
+ * `attachPaymentProofAction`'s guard, the admin payment-review queue, and the
+ * buyer/seller "needs payment proof" UI — previously each site inlined its own
+ * `pm !== "cash" && pm !== "upi_manual" && ...` chain and they could drift.
+ */
+export declare const MANUAL_PAYMENT_METHODS: readonly string[];
+export declare function isManualPaymentMethod(method: string | undefined | null): boolean;
+/**
+ * The two states an unresolved manual payment can be in. Derived at query
+ * time from `paymentProofUrl` + `paymentReviewOutcome` rather than stored as
+ * its own field — a denormalised mirror would drift the moment any write path
+ * forgot it (CLAUDE.md Root Cause Pattern #42).
+ */
+export type PaymentReviewQueueMode = "awaiting_proof" | "awaiting_verification";
+export declare const PAYMENT_REVIEW_QUEUE_MODES: readonly PaymentReviewQueueMode[];
+export declare function isPaymentReviewQueueMode(value: string): value is PaymentReviewQueueMode;
+/**
+ * Hard bound on the payment-review queue's Firestore scan (Rule #6 — the
+ * Vercel 10s sync ceiling). Safe because an order only sits in this queue for
+ * 15 minutes (awaiting proof) or 2 hours (awaiting verification) before a
+ * scheduled sweep resolves it, so the live set is inherently small.
+ */
+export declare const PAYMENT_REVIEW_QUEUE_SCAN_LIMIT = 500;

package/dist/features/orders/constants/payment-window.js

@@ -8,3 +8,28 @@ export const PAYMENT_WINDOW_MS = PAYMENT_WINDOW_MINUTES * 60 * 1000;
 /** Cancellation reasons this feature writes to `OrderDocument.cancellationReason` (a free-form string field). */
 export const PAYMENT_WINDOW_EXPIRED_REASON = "payment_window_expired";
 export const PAYMENT_FRAUD_REJECTED_REASON = "payment_fraud_rejected";
+/**
+ * The `paymentMethod` values that settle out-of-band and therefore require a
+ * buyer-uploaded proof + a human review pass. Single source of truth for
+ * `attachPaymentProofAction`'s guard, the admin payment-review queue, and the
+ * buyer/seller "needs payment proof" UI — previously each site inlined its own
+ * `pm !== "cash" && pm !== "upi_manual" && ...` chain and they could drift.
+ */
+export const MANUAL_PAYMENT_METHODS = ["cash", "upi_manual", "emi"];
+export function isManualPaymentMethod(method) {
+    return !!method && MANUAL_PAYMENT_METHODS.includes(method);
+}
+export const PAYMENT_REVIEW_QUEUE_MODES = [
+    "awaiting_proof",
+    "awaiting_verification",
+];
+export function isPaymentReviewQueueMode(value) {
+    return PAYMENT_REVIEW_QUEUE_MODES.includes(value);
+}
+/**
+ * Hard bound on the payment-review queue's Firestore scan (Rule #6 — the
+ * Vercel 10s sync ceiling). Safe because an order only sits in this queue for
+ * 15 minutes (awaiting proof) or 2 hours (awaiting verification) before a
+ * scheduled sweep resolves it, so the live set is inherently small.
+ */
+export const PAYMENT_REVIEW_QUEUE_SCAN_LIMIT = 500;

package/dist/features/orders/repository/orders.repository.d.ts

@@ -3,6 +3,7 @@ import type { FirebaseSieveResult, SieveModel } from "../../../providers/db-fire
 import { BaseRepository, parseSieveDateValue } from "../../../providers/db-firebase";
 import { type OrderCreateInput, type OrderDocument, type OrderRefundEvent } from "../schemas";
 import type { OrderStatus, PaymentStatus } from "../types";
+import { type PaymentReviewQueueMode } from "../constants/payment-window";
 declare class OrderRepository extends BaseRepository<OrderDocument> {
     constructor();
     private decryptOrder;
@@ -217,6 +218,37 @@ declare class OrderRepository extends BaseRepository<OrderDocument> {
         ref: DocumentReference;
         data: OrderDocument;
     }>>;
+    /**
+     * Admin/seller payment-review queue — the manual-payment orders that are
+     * waiting on somebody. Two modes:
+     *
+     *  - `awaiting_proof`        — buyer hasn't uploaded a screenshot yet
+     *                              (the 15-minute `paymentDeadline` window).
+     *  - `awaiting_verification` — proof submitted, no admin decision recorded
+     *                              yet (the 2-hour auto-approve window).
+     *
+     * Both refinements — proof presence and manual `paymentMethod` — are done
+     * in-memory rather than as Firestore clauses, deliberately:
+     *
+     *  - `paymentProofUrl != null` would silently exclude every doc where the
+     *    field was never set at all, which is exactly the `awaiting_proof` set
+     *    (same reasoning as `getExpiredPaymentDeadlines` /
+     *    `getUnreviewedProofPastDeadline` above).
+     *  - keeping `paymentMethod` out of the query means this reuses the
+     *    existing `(status, paymentStatus, createdAt)` composite index instead
+     *    of needing a new four-field one.
+     *
+     * The scan is hard-bounded at {@link PAYMENT_REVIEW_QUEUE_SCAN_LIMIT} for
+     * the Vercel 10s ceiling. That bound is generous for this queue by
+     * construction: an order only sits in it for 15 minutes (awaiting proof) or
+     * 2 hours (awaiting verification) before a scheduled sweep resolves it, so
+     * the live set is inherently small. `total` therefore counts matches within
+     * the scan window, not an unbounded collection-wide count.
+     */
+    listPaymentReviewQueue(mode: PaymentReviewQueueMode, opts?: {
+        page?: number;
+        pageSize?: number;
+    }): Promise<FirebaseSieveResult<OrderDocument>>;
     /**
      * Cloud Functions: find delivered orders eligible for the weekly payout sweep.
      *

package/dist/features/orders/repository/orders.repository.js

@@ -4,6 +4,7 @@ import { BaseRepository, prepareForFirestore, parseSieveDateValue, } from "../..
 import { decryptPiiFields, encryptPiiFields, ORDER_PII_FIELDS, } from "../../../security";
 import { serverTimestamp } from "../../../contracts/field-ops";
 import { createOrderId, ORDER_COLLECTION, OrderStatusValues, } from "../schemas";
+import { MANUAL_PAYMENT_METHODS, PAYMENT_REVIEW_QUEUE_SCAN_LIMIT, } from "../constants/payment-window";
 import { ORDER_FIELDS } from "../../../constants/field-names";
 /**
  * Statuses that count toward a user's per-product / per-bundle purchase
@@ -340,6 +341,61 @@ class OrderRepository extends BaseRepository {
         }))
             .filter((entry) => !!entry.data.paymentProofUrl && !entry.data.paymentReviewOutcome);
     }
+    /**
+     * Admin/seller payment-review queue — the manual-payment orders that are
+     * waiting on somebody. Two modes:
+     *
+     *  - `awaiting_proof`        — buyer hasn't uploaded a screenshot yet
+     *                              (the 15-minute `paymentDeadline` window).
+     *  - `awaiting_verification` — proof submitted, no admin decision recorded
+     *                              yet (the 2-hour auto-approve window).
+     *
+     * Both refinements — proof presence and manual `paymentMethod` — are done
+     * in-memory rather than as Firestore clauses, deliberately:
+     *
+     *  - `paymentProofUrl != null` would silently exclude every doc where the
+     *    field was never set at all, which is exactly the `awaiting_proof` set
+     *    (same reasoning as `getExpiredPaymentDeadlines` /
+     *    `getUnreviewedProofPastDeadline` above).
+     *  - keeping `paymentMethod` out of the query means this reuses the
+     *    existing `(status, paymentStatus, createdAt)` composite index instead
+     *    of needing a new four-field one.
+     *
+     * The scan is hard-bounded at {@link PAYMENT_REVIEW_QUEUE_SCAN_LIMIT} for
+     * the Vercel 10s ceiling. That bound is generous for this queue by
+     * construction: an order only sits in it for 15 minutes (awaiting proof) or
+     * 2 hours (awaiting verification) before a scheduled sweep resolves it, so
+     * the live set is inherently small. `total` therefore counts matches within
+     * the scan window, not an unbounded collection-wide count.
+     */
+    async listPaymentReviewQueue(mode, opts = {}) {
+        const page = Math.max(1, opts.page ?? 1);
+        const pageSize = Math.min(50, Math.max(1, opts.pageSize ?? 25));
+        const snap = await this.db
+            .collection(this.collection)
+            .where(ORDER_FIELDS.STATUS, "==", OrderStatusValues.PENDING)
+            .where(ORDER_FIELDS.PAYMENT_STATUS, "==", "pending")
+            .orderBy(ORDER_FIELDS.CREATED_AT, "desc")
+            .limit(PAYMENT_REVIEW_QUEUE_SCAN_LIMIT)
+            .get();
+        const matches = snap.docs
+            .map((d) => this.decryptOrder({ id: d.id, ...d.data() }))
+            .filter((order) => MANUAL_PAYMENT_METHODS.includes(order.paymentMethod ?? ""))
+            .filter((order) => mode === "awaiting_proof"
+            ? !order.paymentProofUrl
+            : !!order.paymentProofUrl && !order.paymentReviewOutcome);
+        const total = matches.length;
+        const totalPages = total === 0 ? 0 : Math.max(1, Math.ceil(total / pageSize));
+        const start = (page - 1) * pageSize;
+        return {
+            items: matches.slice(start, start + pageSize),
+            total,
+            page,
+            pageSize,
+            totalPages,
+            hasMore: page < totalPages,
+        };
+    }
     /**
      * Cloud Functions: find delivered orders eligible for the weekly payout sweep.
      *