@mohasinac/appkit 4.52.5 → 4.53.1

package/dist/features/layout/useHoldToOpen.d.ts

@@ -0,0 +1,41 @@
+import React 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 declare 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 declare function useHoldToOpen(onHold: () => void, enabled?: boolean): {
+    onPointerDown: () => void;
+    onPointerUp: () => void;
+    onPointerLeave: () => void;
+    onPointerCancel: () => void;
+    onClickCapture: (e: React.MouseEvent) => void;
+    onContextMenu: (e: React.MouseEvent) => void;
+} | {
+    onPointerDown?: undefined;
+    onPointerUp?: undefined;
+    onPointerLeave?: undefined;
+    onPointerCancel?: undefined;
+    onClickCapture?: undefined;
+    onContextMenu?: undefined;
+};

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/live/components/LiveItemDetailPageView.js

@@ -1,7 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import Link from "next/link.js";
 import { getLiveItemForDetail } from "../../../_internal/server/features/live/data.js";
-const CLS_BREADCRUMB_LINK = "hover:text-primary-600 transition-colors";
+const CLS_BREADCRUMB_LINK = "hover:text-primary-600 dark:hover:text-primary-400 transition-colors";
 const CLS_LIVE_ITEM_BADGE = "inline-block rounded-full bg-lime-100 dark:bg-lime-900/30 px-[var(--appkit-space-2-5)] py-[var(--appkit-space-0-5)] text-lime-700 dark:text-lime-300";
 const CLS_WARN_BOX = "rounded-lg border border-warning bg-warning-surface p-[var(--appkit-space-4)] text-[length:var(--appkit-text-sm)]";
 const CLS_WARN_TITLE = "font-medium text-warning";
@@ -11,11 +11,11 @@ import { getDefaultCurrency } from "../../../core/baseline-resolver.js";
 import { formatCurrency } from "../../../utils/number.formatter.js";
 import { normalizeRichTextHtml } from "../../../utils/string.formatter.js";
 import { safeDisplayName } from "../../../security/index.js";
-import { Div, Container, GatedPrice, PricesOnly, Heading, Main, Nav, RichText, Row, Section, Span, Stack, Text, Dl, Dt, Dd, } from "../../../ui/index.js";
+import { Div, Container, GatedPrice, PricesOnly, Heading, Main, Nav, RichText, Row, Section, Span, Stack, Text, SpecTable, } from "../../../ui/index.js";
 import { PreOrderDetailView } from "../../products/components/PreOrderDetailView.js";
 import { ProductGalleryClient } from "../../products/components/ProductGalleryClient.js";
 import { ProductTabsShell } from "../../products/components/ProductTabsShell.js";
-import { CustomSectionTabContent } from "../../products/components/CustomSectionTabContent.js";
+import { toCustomSectionTabs } from "../../products/components/CustomSectionTabContent.js";
 import { ShareButton } from "../../products/components/ShareButton.js";
 import { HistoryTracker } from "../../history/components/HistoryTracker.js";
 import { RelatedItemsSection } from "../../products/components/RelatedItemsSection.js";
@@ -57,7 +57,6 @@ export async function LiveItemDetailPageView({ slug, initialProduct, renderActio
     const storeSlug = (typeof p.storeSlug === "string" ? p.storeSlug : null) || (typeof p.storeId === "string" ? p.storeId : null);
     const storeHref = storeSlug ? String(ROUTES.PUBLIC.STORE_DETAIL(storeSlug)) : null;
     const specs = Array.isArray(p.specifications) ? p.specifications : [];
-    const customSections = Array.isArray(p.customSections) ? p.customSections : [];
     const descriptionHtml = toDescriptionHtml(p.description);
     const [{ relatedItems, relatedByBrand, relatedByTags, relatedByStore }, groups, initialReviews] = await Promise.all([
         computeRelatedItems(product),
@@ -70,9 +69,5 @@ export async function LiveItemDetailPageView({ slug, initialProduct, renderActio
                     price: price ?? undefined,
                     storeId: typeof p.storeId === "string" ? p.storeId : undefined,
                     storeName: storeName ?? undefined,
-                } }), _jsxs(Container, { size: "xl", padding: "y-lg", children: [_jsxs(Row, { className: "mb-4", align: "center", justify: "between", gap: "sm", wrap: true, children: [_jsxs(Nav, { "aria-label": "Breadcrumb", layout: "flex-wrap", gap: "2xs", textSize: "xs", color: "muted", children: [_jsx(Link, { href: String(ROUTES.HOME), className: CLS_BREADCRUMB_LINK, children: "Home" }), _jsx(Span, { "aria-hidden": true, children: "/" }), _jsx(Link, { href: String(ROUTES.PUBLIC.LIVE), className: CLS_BREADCRUMB_LINK, children: "Live" }), category && (_jsxs(_Fragment, { children: [_jsx(Span, { "aria-hidden": true, children: "/" }), _jsx(Link, { href: String(ROUTES.PUBLIC.CATEGORY_DETAIL(category)), className: CLS_BREADCRUMB_LINK, children: categoryName || category })] })), _jsx(Span, { "aria-hidden": true, children: "/" }), _jsx(Span, { className: "truncate max-w-[200px]", color: "muted", children: title })] }), _jsx(ShareButton, { title: title })] }), _jsx(PreOrderDetailView, { renderGallery: () => _jsx(ProductGalleryClient, { images: images, video: productVideo, productName: title }), renderInfo: () => (_jsxs(Stack, { gap: "md", children: [_jsxs(Div, { children: [_jsxs(Row, { gap: "xs", wrap: true, className: "mb-2", children: [_jsx(Span, { size: "xs", weight: "semibold", className: CLS_LIVE_ITEM_BADGE, children: "Live Item" }), meta?.vendorVerified && (_jsx(Span, { color: "success", surface: "success-surface", size: "xs", weight: "medium", className: "inline-block", padding: "pill-sm", rounded: "full", children: "Verified Seller" })), meta?.cites && (_jsxs(Span, { color: "warning", surface: "warning-surface", size: "xs", weight: "medium", className: "inline-block", padding: "pill-sm", rounded: "full", children: ["CITES: ", meta.cites] }))] }), _jsx(Heading, { level: 1, className: "leading-snug", smSize: "2xl", color: "primary", size: "xl", weight: "bold", children: title }), meta?.species && (_jsxs(Text, { className: "italic mt-1", color: "muted", size: "sm", children: [meta.species, meta.sex && meta.sex !== "n/a" && ` · ${meta.sex}`, meta.ageMonths !== undefined && ` · ${meta.ageMonths}mo`] }))] }), price !== null && (_jsx(Text, { size: "2xl", weight: "bold", color: "primary", children: _jsx(GatedPrice, { children: formatCurrency(price, currency) }) })), jurisdictions.length > 0 && (_jsxs(Div, { className: CLS_WARN_BOX, children: [_jsx(Text, { className: CLS_WARN_TITLE, children: "Delivery restrictions" }), _jsxs(Text, { className: CLS_WARN_BODY, children: ["This item can only be shipped to: ", jurisdictions.join(", ")] })] })), transport && (_jsxs(Div, { textSize: "sm", border: "subtle", surface: "muted", padding: "md", rounded: "lg", children: [_jsx(Text, { weight: "medium", children: "Transport" }), _jsxs(Text, { className: "text-[var(--appkit-color-text-muted)]", children: ["Method: ", transport.method, transport.handlingFee !== undefined && (_jsx(PricesOnly, { children: ` · Handling: ${formatCurrency(transport.handlingFee, "INR")}` })), transport.insuranceIncluded && " · Insurance included"] })] })), meta?.careInfo && (_jsxs(Div, { textSize: "sm", border: "subtle", surface: "muted", padding: "md", rounded: "lg", children: [_jsx(Text, { weight: "medium", children: "Care information" }), _jsx(Text, { className: "mt-1 text-[var(--appkit-color-text-muted)]", children: meta.careInfo })] })), descriptionHtml && (_jsx(RichText, { html: descriptionHtml, proseClass: "prose prose-sm max-w-none dark:prose-invert prose-p:my-0", className: "text-[length:var(--appkit-text-sm)] leading-relaxed text-[var(--appkit-color-text-muted)] line-clamp-4" })), safeSeller && (_jsx(Div, { border: "subtle", rounded: "xl", surface: "muted", padding: "md", children: _jsxs(Row, { justify: "between", align: "center", children: [_jsxs(Div, { children: [_jsx(Text, { className: "text-[10px] tracking-wide mb-0.5", color: "faint", transform: "uppercase", children: "Sold by" }), _jsx(Text, { size: "sm", weight: "semibold", color: "primary", children: safeSeller })] }), storeHref && (_jsx(Link, { href: storeHref, className: "shrink-0 rounded-lg bg-primary/10 dark:bg-primary/20 px-[var(--appkit-space-3)] py-[var(--appkit-space-1-5)] text-[length:var(--appkit-text-xs)] font-semibold text-primary-700 dark:text-primary-300 hover:bg-primary/20 dark:hover:bg-primary/30 transition-colors", children: "Visit Store \u2192" }))] }) }))] })), renderTabs: () => (_jsx(ProductTabsShell, { descriptionContent: descriptionHtml ? (_jsx(RichText, { html: descriptionHtml, proseClass: "prose prose-sm sm:prose max-w-none dark:prose-invert", className: "text-[var(--appkit-color-text-muted)]" })) : undefined, specsContent: specs.length > 0 ? (_jsx(Dl, { divide: "subtle", rounded: "xl", border: "subtle", className: "overflow-hidden", children: specs.map((s, i) => (_jsxs(Row, { gap: "md", oddEven: "zebra", surface: "default", padding: "inline", children: [_jsx(Dt, { className: "w-36 flex-shrink-0", color: "primary", weight: "medium", children: s.name }), _jsxs(Dd, { className: "flex-1", color: "muted", children: [s.value, s.unit ? ` ${s.unit}` : ""] })] }, i))) })) : undefined, reviewsContent: _jsx(ReviewsListingPanel, { source: { kind: "product", productId: product.id }, stateMode: "local", context: "listing", initialData: initialReviews, emptyLabel: "No reviews yet \u2014 be the first to review this product." }), customTabs: customSections.map((s) => ({
-                                id: s.id,
-                                label: s.title,
-                                content: _jsx(CustomSectionTabContent, { section: s }),
-                            })) })), renderBuyBar: () => _jsx(Div, { id: "live-item-buy-bar", children: renderActions?.(product) }), renderRelated: () => (_jsxs(Stack, { gap: "xl", children: [_jsx(GroupedListingsCarousel, { groups: groups }), _jsx(RelatedItemsSection, { relatedItems: relatedItems, relatedByBrand: relatedByBrand, relatedByTags: relatedByTags, relatedByStore: relatedByStore, categoryLabel: categoryName || category || undefined, brandLabel: brand, storeLabel: storeName ?? undefined })] })) }), _jsx(ListingBottomActions, { listingType: "live", anchorId: "live-item-buy-bar", price: price, currency: currency })] })] }));
+                } }), _jsxs(Container, { size: "xl", padding: "y-lg", children: [_jsxs(Row, { className: "mb-4", align: "center", justify: "between", gap: "sm", wrap: true, children: [_jsxs(Nav, { "aria-label": "Breadcrumb", layout: "flex-wrap", gap: "2xs", textSize: "xs", color: "muted", children: [_jsx(Link, { href: String(ROUTES.HOME), className: CLS_BREADCRUMB_LINK, children: "Home" }), _jsx(Span, { "aria-hidden": true, children: "/" }), _jsx(Link, { href: String(ROUTES.PUBLIC.LIVE), className: CLS_BREADCRUMB_LINK, children: "Live" }), category && (_jsxs(_Fragment, { children: [_jsx(Span, { "aria-hidden": true, children: "/" }), _jsx(Link, { href: String(ROUTES.PUBLIC.CATEGORY_DETAIL(category)), className: CLS_BREADCRUMB_LINK, children: categoryName || category })] })), _jsx(Span, { "aria-hidden": true, children: "/" }), _jsx(Span, { className: "truncate max-w-[200px]", color: "muted", children: title })] }), _jsx(ShareButton, { title: title })] }), _jsx(PreOrderDetailView, { renderGallery: () => _jsx(ProductGalleryClient, { images: images, video: productVideo, productName: title }), renderInfo: () => (_jsxs(Stack, { gap: "md", children: [_jsxs(Div, { children: [_jsxs(Row, { gap: "xs", wrap: true, className: "mb-2", children: [_jsx(Span, { size: "xs", weight: "semibold", className: CLS_LIVE_ITEM_BADGE, children: "Live Item" }), meta?.vendorVerified && (_jsx(Span, { color: "success", surface: "success-surface", size: "xs", weight: "medium", className: "inline-block", padding: "pill-sm", rounded: "full", children: "Verified Seller" })), meta?.cites && (_jsxs(Span, { color: "warning", surface: "warning-surface", size: "xs", weight: "medium", className: "inline-block", padding: "pill-sm", rounded: "full", children: ["CITES: ", meta.cites] }))] }), _jsx(Heading, { level: 1, className: "leading-snug", smSize: "2xl", color: "primary", size: "xl", weight: "bold", children: title }), meta?.species && (_jsxs(Text, { className: "italic mt-1", color: "muted", size: "sm", children: [meta.species, meta.sex && meta.sex !== "n/a" && ` · ${meta.sex}`, meta.ageMonths !== undefined && ` · ${meta.ageMonths}mo`] }))] }), price !== null && (_jsx(Text, { size: "2xl", weight: "bold", color: "primary", children: _jsx(GatedPrice, { children: formatCurrency(price, currency) }) })), jurisdictions.length > 0 && (_jsxs(Div, { className: CLS_WARN_BOX, children: [_jsx(Text, { className: CLS_WARN_TITLE, children: "Delivery restrictions" }), _jsxs(Text, { className: CLS_WARN_BODY, children: ["This item can only be shipped to: ", jurisdictions.join(", ")] })] })), transport && (_jsxs(Div, { textSize: "sm", border: "subtle", surface: "muted", padding: "md", rounded: "lg", children: [_jsx(Text, { weight: "medium", children: "Transport" }), _jsxs(Text, { className: "text-[var(--appkit-color-text-muted)]", children: ["Method: ", transport.method, transport.handlingFee !== undefined && (_jsx(PricesOnly, { children: ` · Handling: ${formatCurrency(transport.handlingFee, "INR")}` })), transport.insuranceIncluded && " · Insurance included"] })] })), meta?.careInfo && (_jsxs(Div, { textSize: "sm", border: "subtle", surface: "muted", padding: "md", rounded: "lg", children: [_jsx(Text, { weight: "medium", children: "Care information" }), _jsx(Text, { className: "mt-1 text-[var(--appkit-color-text-muted)]", children: meta.careInfo })] })), descriptionHtml && (_jsx(RichText, { html: descriptionHtml, proseClass: "prose prose-sm max-w-none dark:prose-invert prose-p:my-0", className: "text-[length:var(--appkit-text-sm)] leading-relaxed text-[var(--appkit-color-text-muted)] line-clamp-4" })), safeSeller && (_jsx(Div, { border: "subtle", rounded: "xl", surface: "muted", padding: "md", children: _jsxs(Row, { justify: "between", align: "center", children: [_jsxs(Div, { children: [_jsx(Text, { className: "text-[10px] tracking-wide mb-0.5", color: "faint", transform: "uppercase", children: "Sold by" }), _jsx(Text, { size: "sm", weight: "semibold", color: "primary", children: safeSeller })] }), storeHref && (_jsx(Link, { href: storeHref, className: "shrink-0 rounded-lg bg-primary/10 dark:bg-primary/20 px-[var(--appkit-space-3)] py-[var(--appkit-space-1-5)] text-[length:var(--appkit-text-xs)] font-semibold text-primary-700 dark:text-primary-300 hover:bg-primary/20 dark:hover:bg-primary/30 transition-colors", children: "Visit Store \u2192" }))] }) }))] })), renderTabs: () => (_jsx(ProductTabsShell, { descriptionContent: descriptionHtml ? (_jsx(RichText, { html: descriptionHtml, proseClass: "prose prose-sm sm:prose max-w-none dark:prose-invert", className: "text-[var(--appkit-color-text-muted)]" })) : undefined, specsContent: specs.length > 0 ? (_jsx(SpecTable, { rows: specs })) : undefined, reviewsContent: _jsx(ReviewsListingPanel, { source: { kind: "product", productId: product.id }, stateMode: "local", context: "listing", initialData: initialReviews, emptyLabel: "No reviews yet \u2014 be the first to review this product." }), customTabs: toCustomSectionTabs(p.customSections) })), renderBuyBar: () => _jsx(Div, { id: "live-item-buy-bar", children: renderActions?.(product) }), renderRelated: () => (_jsxs(Stack, { gap: "xl", children: [_jsx(GroupedListingsCarousel, { groups: groups }), _jsx(RelatedItemsSection, { relatedItems: relatedItems, relatedByBrand: relatedByBrand, relatedByTags: relatedByTags, relatedByStore: relatedByStore, categoryLabel: categoryName || category || undefined, brandLabel: brand, storeLabel: storeName ?? undefined })] })) }), _jsx(ListingBottomActions, { listingType: "live", anchorId: "live-item-buy-bar", price: price, currency: currency })] })] }));
 }

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/hooks/useMedia.js

@@ -58,6 +58,23 @@ export function useMediaUpload(endpoints = {}) {
             return apiClient.post(finalizeEndpoint, {
                 storagePath: signResponse.storagePath,
                 isPublic,
+                /*
+                 * A7 — the ORIGINAL client filename, for the provenance heuristics.
+                 *
+                 * 🛑 It cannot be derived server-side. Our own `storagePath` is a
+                 * content-derived SEO slug minted at sign time (§ Media Filename Slug
+                 * Patterns), so by the time the server sees the upload the only name
+                 * left is one we invented — and the signals A7 looks for (Amazon's
+                 * `_AC_SL1500_`, a generator's `ChatGPT-Image-…`) live exclusively in
+                 * the name the file arrived with.
+                 *
+                 * Advisory and client-supplied, therefore trivially spoofable. That is
+                 * acceptable because nothing gates on it: it raises a flag for a human,
+                 * and a seller who renames a file to avoid one has merely declined to
+                 * volunteer information. Never treat it as evidence of anything but
+                 * itself.
+                 */
+                originalFilename: file.name,
             });
         },
     });

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,12 +21,77 @@ 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;
+    /**
+     * A7 — provenance concerns recorded for human review. See
+     * `features/media/trust-signals.ts` for the vocabulary and, more
+     * importantly, for what is deliberately NOT flagged.
+     *
+     * 🛑 ADVISORY. Nothing reads this to block an upload, hide a listing or
+     * refuse a seller; it exists so a moderator can look. A heuristic that
+     * auto-rejects refuses honest sellers on a filename.
+     *
+     * Absent means "not evaluated" (every row predating A7, and every non-image
+     * asset), which is NOT the same as "clean" — a reader must not treat the
+     * absence as a pass.
+     */
+    trustFlags?: string[];
+    /**
+     * A7 — 16-char hex dHash of the image, for near-duplicate detection.
+     *
+     * Perceptual, not cryptographic: stable across re-encoding and resizing, so
+     * it answers "is this the same photograph" rather than "is this the same
+     * file". Images only; absent when the hash could not be computed, which is
+     * deliberately non-fatal.
+     */
+    dHash?: string;
     createdAt: Date;
 }
 export type MediaAssetCreateInput = Omit<MediaAssetDocument, "id" | "createdAt">;
 export declare class MediaAssetsRepository extends BaseRepository<MediaAssetDocument> {
     constructor();
     findByStoragePath(storagePath: string): Promise<MediaAssetDocument | null>;
+    /**
+     * A7 — assets sharing a dHash, for the cross-seller duplicate check.
+     *
+     * 🛑 BOUNDED, and exact-match only. An equality on `dHash` is served by
+     * Firestore's automatic single-field index, so this needs no composite —
+     * whereas a true nearest-neighbour search over 64-bit hashes would need
+     * either a full scan or a BK-tree, and a full collection scan on every
+     * upload is precisely the unbounded-read shape Rule #6 exists to prevent.
+     *
+     * 🛑 The trade is narrower than it first looks, and it was MEASURED rather
+     * than assumed. Against the same source image:
+     *
+     *     resized to 220px wide     -> distance 0   (exact match CATCHES it)
+     *     re-encoded jpeg q55       -> distance 3   (exact match MISSES it)
+     *     a different bey entirely  -> distance 9
+     *
+     * So this online check reliably catches a RESIZE and will miss a re-encode.
+     * An earlier revision of this comment claimed both produce an identical
+     * hash; that was wrong. `dHashDistance` and `DHASH_DUPLICATE_MAX_DISTANCE`
+     * are exported for an offline sweep that can afford the pairwise
+     * comparison, which is where the distance-3 case gets caught.
+     */
+    findByDHash(dHash: string, limit?: number): Promise<MediaAssetDocument[]>;
     /**
      * Create a new mediaAssets document with a collision-safe shortId.
      * Tries `preferredShortId` first, then appends a random 4-char suffix up to

package/dist/features/media/repository/media-assets.repository.js

@@ -12,6 +12,37 @@ export class MediaAssetsRepository extends BaseRepository {
     async findByStoragePath(storagePath) {
         return this.findOneBy("storagePath", storagePath);
     }
+    /**
+     * A7 — assets sharing a dHash, for the cross-seller duplicate check.
+     *
+     * 🛑 BOUNDED, and exact-match only. An equality on `dHash` is served by
+     * Firestore's automatic single-field index, so this needs no composite —
+     * whereas a true nearest-neighbour search over 64-bit hashes would need
+     * either a full scan or a BK-tree, and a full collection scan on every
+     * upload is precisely the unbounded-read shape Rule #6 exists to prevent.
+     *
+     * 🛑 The trade is narrower than it first looks, and it was MEASURED rather
+     * than assumed. Against the same source image:
+     *
+     *     resized to 220px wide     -> distance 0   (exact match CATCHES it)
+     *     re-encoded jpeg q55       -> distance 3   (exact match MISSES it)
+     *     a different bey entirely  -> distance 9
+     *
+     * So this online check reliably catches a RESIZE and will miss a re-encode.
+     * An earlier revision of this comment claimed both produce an identical
+     * hash; that was wrong. `dHashDistance` and `DHASH_DUPLICATE_MAX_DISTANCE`
+     * are exported for an offline sweep that can afford the pairwise
+     * comparison, which is where the distance-3 case gets caught.
+     */
+    async findByDHash(dHash, limit = 5) {
+        if (!dHash)
+            return [];
+        const snapshot = await this.getCollection()
+            .where("dHash", "==", dHash)
+            .limit(limit)
+            .get();
+        return snapshot.docs.map((d) => this.mapDoc(d));
+    }
     /**
      * Create a new mediaAssets document with a collision-safe shortId.
      * Tries `preferredShortId` first, then appends a random 4-char suffix up to