@mohasinac/appkit 4.53.0 → 4.53.2

package/dist/features/products/schemas/firestore.js

@@ -2,6 +2,74 @@
  * Products Firestore Document Types & Constants
  */
 import { generateProductId, generateAuctionId, generatePreOrderId, } from "../../../utils/id-generators.js";
+/**
+ * Whatever a document, a request body or a seed row happens to hold, as
+ * `ProductImage[]`.
+ *
+ * 🛑 This is called on the WRITE path (`ProductRepository.create`/`update`)
+ * **and** on the read path (`mapDoc`), and both are required. Root Cause #101
+ * is exactly this shape: `mapDoc` backfilled `categorySlugs` on read while the
+ * write schema stripped it, so the field was present on every object anyone
+ * inspected and absent from the stored document — invisible to every query,
+ * and latent until a human created a listing.
+ *
+ * Accepts `string`, `ProductImage`, and a mixed array of both, because a
+ * partially-migrated collection genuinely contains all three.
+ */
+export function toProductImages(input) {
+    if (!Array.isArray(input))
+        return [];
+    const out = [];
+    for (const entry of input) {
+        if (typeof entry === "string") {
+            if (entry)
+                out.push({ url: entry });
+            continue;
+        }
+        if (entry && typeof entry === "object") {
+            /*
+             * `Partial<ProductImage>`, NOT `{ url?: unknown }` — one narrowing
+             * instead of two casts, and no `unknown` in a local binding
+             * (`audit-unknown-leakage` flagged the earlier spelling, correctly: an
+             * `unknown` here defeats the checking on every member read below it).
+             * Every member is still validated before use, so the assertion is
+             * narrowing a shape we are about to prove rather than asserting a fact.
+             */
+            const e = entry;
+            if (typeof e.url !== "string" || !e.url)
+                continue;
+            /*
+             * 🛑 EVERY optional member is carried through, not just the two A6
+             * added. This runs on the WRITE path, so a member it forgets is a
+             * member it DESTROYS on the next save — and `thumbnailUrl`/`order`
+             * predate this function. Adding a field to `ProductImage` means adding
+             * it here; the alternative is a normaliser that quietly truncates the
+             * type it claims to normalise.
+             */
+            out.push({
+                url: e.url,
+                ...(e.alt ? { alt: e.alt } : {}),
+                ...(e.thumbnailUrl ? { thumbnailUrl: e.thumbnailUrl } : {}),
+                ...(typeof e.order === "number" ? { order: e.order } : {}),
+                ...(typeof e.width === "number" ? { width: e.width } : {}),
+                ...(typeof e.height === "number" ? { height: e.height } : {}),
+            });
+        }
+    }
+    return out;
+}
+/**
+ * Just the URLs, in order — for the many call sites that only ever needed a
+ * `string[]` (a lightbox's source list, an OG image pick, a media-abort
+ * cleanup list).
+ *
+ * This is a PROJECTION, computed on demand, not a stored mirror — so it cannot
+ * drift from `images` the way a denormalised second field would (Root Cause
+ * #42). Takes `unknown` so it also works on a legacy `string[]`.
+ */
+export function productImageUrls(input) {
+    return toProductImages(input).map((i) => i.url);
+}
 export const MAX_CUSTOM_FIELDS = 50;
 export const MAX_CUSTOM_SECTIONS = 3;
 /** Runtime-accessible product status values — use instead of bare string literals. */
@@ -171,6 +239,15 @@ export const PRODUCT_PUBLIC_FIELDS = [
     "isPromoted",
     "isOnSale",
     "isSold",
+    /* Public because the PDP has to SAY "made to order, printed when you order"
+     * instead of a stock line, and the group picker has to uncap that member's
+     * stepper. Both are client-side reads. */
+    "madeToOrder",
+    /* Public: provenance a buyer should see — "this is one cut off that sheet" —
+     * and neither value is a path or a private id. The sheet document itself is
+     * admin-only; this is just its id, same shape as `sourceCatalogueItemId`. */
+    "sourceStickerSheetId",
+    "sourceStickerPartOrdinal",
     "slug",
     "seoTitle",
     "seoDescription",
@@ -184,6 +261,14 @@ export const PRODUCT_PUBLIC_FIELDS = [
     "groupParentSlug",
     "groupChildSlugs",
     "groupTitle",
+    /* The group's own rules. Public because the PICKER enforces them too — a
+     * server-only rule reads as a broken button — and none of them is sensitive:
+     * they are merchandising limits a buyer is about to be told anyway. */
+    "groupMinMembers",
+    "groupMaxMembers",
+    "groupMaxUnitsPerMember",
+    "groupRequiredMemberIds",
+    "groupDiscountPercent",
     "createdAt",
 ];
 export const PRODUCT_UPDATABLE_FIELDS = [
@@ -250,6 +335,17 @@ export const PRODUCT_UPDATABLE_FIELDS = [
     "preOrderCancellable",
     "isOnSale",
     "isSold",
+    /* 🛑 Listed here or an update STRIPS it — the write schema has no
+     * `.passthrough()`, so a field absent from this list is dropped before it
+     * reaches Firestore while the write still returns 200 (Root Cause #101). The
+     * seller checkbox would appear to save and change nothing. */
+    "madeToOrder",
+    /* Updatable so `promoteStickerSheetToListings` can set them through the same
+     * `create`/`update` path every other write uses — and so a re-promote can
+     * correct them — rather than needing a raw collection write that would also
+     * skip `deriveTaxonomy`. */
+    "sourceStickerSheetId",
+    "sourceStickerPartOrdinal",
     "allowShipBeforeEmiComplete",
     /*
      * B3 — these three were MISSING, so the fields existed on the document
@@ -272,6 +368,14 @@ export const PRODUCT_UPDATABLE_FIELDS = [
     "groupParentSlug",
     "groupChildSlugs",
     "groupTitle",
+    /* The group's own rules. Public because the PICKER enforces them too — a
+     * server-only rule reads as a broken button — and none of them is sensitive:
+     * they are merchandising limits a buyer is about to be told anyway. */
+    "groupMinMembers",
+    "groupMaxMembers",
+    "groupMaxUnitsPerMember",
+    "groupRequiredMemberIds",
+    "groupDiscountPercent",
     "barcodeId",
 ];
 // ── SB-UNI-N 2026-05-15 — Digital-code pool subcollection ───────────────────

package/dist/features/products/schemas/index.d.ts

@@ -1,5 +1,6 @@
 export * from "./firestore";
 import { z } from "zod";
+import type { ListingType } from "../types/index";
 export declare const productImageSchema: z.ZodObject<{
     url: z.ZodString;
     thumbnailUrl: z.ZodOptional<z.ZodString>;
@@ -46,19 +47,6 @@ export declare const printMetaSchema: z.ZodObject<{
     finish?: string | undefined;
     editionSize?: number | undefined;
 }>;
-/**
- * Base Zod schema for a product item.
- * Apps can extend this to add their own fields:
- *
- * @example
- * import { productItemSchema } from "@mohasinac/feat-products";
- *
- * const myProductSchema = productItemSchema.extend({
- *   brand: z.string(),
- *   auctionEndDate: z.string().optional(),
- * });
- * type MyProduct = z.infer<typeof myProductSchema>;
- */
 export declare const productItemSchema: z.ZodObject<{
     id: z.ZodString;
     title: z.ZodString;
@@ -130,7 +118,8 @@ export declare const productItemSchema: z.ZodObject<{
     sellerAvatar: z.ZodOptional<z.ZodString>;
     status: z.ZodEnum<["draft", "published", "in_review", "archived"]>;
     condition: z.ZodOptional<z.ZodEnum<["new", "like_new", "good", "fair", "poor", "used", "refurbished", "broken", "graded"]>>;
-    listingType: z.ZodOptional<z.ZodEnum<["standard", "auction", "pre-order", "prize-draw", "classified", "digital-code", "live"]>>;
+    madeToOrder: z.ZodOptional<z.ZodBoolean>;
+    listingType: z.ZodOptional<z.ZodEnum<[ListingType, ...ListingType[]]>>;
     maxPerUser: z.ZodOptional<z.ZodNumber>;
     partOfBundleIds: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     partOfBundleTitles: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
@@ -337,7 +326,7 @@ export declare const productItemSchema: z.ZodObject<{
     } | undefined;
     createdAt?: string | undefined;
     updatedAt?: string | undefined;
-    listingType?: "classified" | "standard" | "auction" | "pre-order" | "prize-draw" | "digital-code" | "live" | undefined;
+    listingType?: ListingType | undefined;
     category?: string | undefined;
     categorySlug?: string | undefined;
     storeId?: string | undefined;
@@ -359,6 +348,7 @@ export declare const productItemSchema: z.ZodObject<{
     description?: string | undefined;
     subcategory?: string | undefined;
     availableQuantity?: number | undefined;
+    madeToOrder?: boolean | undefined;
     mainImage?: string | undefined;
     images?: string[] | undefined;
     featured?: boolean | undefined;
@@ -476,7 +466,7 @@ export declare const productItemSchema: z.ZodObject<{
     } | undefined;
     createdAt?: string | undefined;
     updatedAt?: string | undefined;
-    listingType?: "classified" | "standard" | "auction" | "pre-order" | "prize-draw" | "digital-code" | "live" | undefined;
+    listingType?: ListingType | undefined;
     category?: string | undefined;
     categorySlug?: string | undefined;
     storeId?: string | undefined;
@@ -498,6 +488,7 @@ export declare const productItemSchema: z.ZodObject<{
     description?: string | undefined;
     subcategory?: string | undefined;
     availableQuantity?: number | undefined;
+    madeToOrder?: boolean | undefined;
     mainImage?: string | undefined;
     images?: string[] | undefined;
     featured?: boolean | undefined;
@@ -612,7 +603,7 @@ export declare const productListParamsSchema: z.ZodObject<{
     minPrice: z.ZodOptional<z.ZodNumber>;
     maxPrice: z.ZodOptional<z.ZodNumber>;
     inStock: z.ZodOptional<z.ZodBoolean>;
-    listingType: z.ZodOptional<z.ZodEnum<["standard", "auction", "pre-order", "prize-draw", "classified", "digital-code", "live"]>>;
+    listingType: z.ZodOptional<z.ZodEnum<[ListingType, ...ListingType[]]>>;
     storeId: z.ZodOptional<z.ZodString>;
     sort: z.ZodOptional<z.ZodString>;
     page: z.ZodOptional<z.ZodNumber>;
@@ -623,7 +614,7 @@ export declare const productListParamsSchema: z.ZodObject<{
     status?: "published" | "draft" | "in_review" | "archived" | undefined;
     page?: number | undefined;
     q?: string | undefined;
-    listingType?: "classified" | "standard" | "auction" | "pre-order" | "prize-draw" | "digital-code" | "live" | undefined;
+    listingType?: ListingType | undefined;
     category?: string | undefined;
     storeId?: string | undefined;
     featured?: boolean | undefined;
@@ -637,7 +628,7 @@ export declare const productListParamsSchema: z.ZodObject<{
     status?: "published" | "draft" | "in_review" | "archived" | undefined;
     page?: number | undefined;
     q?: string | undefined;
-    listingType?: "classified" | "standard" | "auction" | "pre-order" | "prize-draw" | "digital-code" | "live" | undefined;
+    listingType?: ListingType | undefined;
     category?: string | undefined;
     storeId?: string | undefined;
     featured?: boolean | undefined;

package/dist/features/products/schemas/index.js

@@ -1,6 +1,7 @@
 export * from "./firestore.js";
 import { z } from "zod";
 import { mediaFieldSchema } from "../../media/types/index.js";
+import { ALL_LISTING_TYPES } from "../../../_internal/shared/listing-types/feature-flags.js";
 import { PRIZE_DRAW_DURATION_DAYS_MIN, PRIZE_DRAW_DURATION_DAYS_MAX, } from "../../../_internal/shared/checkout/rules/_limits.js";
 // --- Sub-schemas --------------------------------------------------------------
 export const productImageSchema = z.object({
@@ -35,6 +36,25 @@ export const printMetaSchema = z.object({
  * });
  * type MyProduct = z.infer<typeof myProductSchema>;
  */
+/**
+ * The `ListingType` union as a Zod enum, DERIVED.
+ *
+ * 🛑 Two hand-written copies of this lived in this file and BOTH had drifted to
+ * seven of nine — `art` and `stickers` were missing from the item schema and
+ * from the query schema. Consequence: `productItemSchema.parse()` stripped
+ * `listingType` off every art and sticker row (the field is `.optional()`, so a
+ * value outside the enum is a parse FAILURE, and a caller using `safeParse` or
+ * `.partial()` loses it silently), and `?listingType=art` on any route
+ * validating against the query schema was rejected as an invalid value.
+ *
+ * `z.enum` needs a non-empty literal tuple, hence the cast — `ALL_LISTING_TYPES`
+ * is derived from `Record<ListingType, true>`, so its CONTENTS are
+ * compile-checked against the union even though its length is not.
+ *
+ * Registered in `audit-listing-type-tab-coverage`'s STAYS_DERIVED so nobody
+ * re-expands it into a literal for readability.
+ */
+const LISTING_TYPE_ENUM = z.enum(ALL_LISTING_TYPES);
 export const productItemSchema = z.object({
     id: z.string(),
     title: z.string(),
@@ -78,9 +98,8 @@ export const productItemSchema = z.object({
     ])
         .optional(),
     // SB1-G Phase 4 — canonical discriminator (legacy `isAuction`/`isPreOrder` booleans removed).
-    listingType: z
-        .enum(["standard", "auction", "pre-order", "prize-draw", "classified", "digital-code", "live"])
-        .optional(),
+    madeToOrder: z.boolean().optional(),
+    listingType: LISTING_TYPE_ENUM.optional(),
     // SB1-C — prize-draw + bundle fields. All optional.
     maxPerUser: z.number().int().positive().optional(),
     partOfBundleIds: z.array(z.string()).optional(),
@@ -229,9 +248,7 @@ export const productListParamsSchema = z.object({
     minPrice: z.coerce.number().optional(),
     maxPrice: z.coerce.number().optional(),
     inStock: z.coerce.boolean().optional(),
-    listingType: z
-        .enum(["standard", "auction", "pre-order", "prize-draw", "classified", "digital-code", "live"])
-        .optional(),
+    listingType: LISTING_TYPE_ENUM.optional(),
     storeId: z.string().optional(),
     sort: z.string().optional(),
     page: z.coerce.number().optional(),

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

@@ -11,12 +11,34 @@ export type ProductCondition = "new" | "like_new" | "good" | "fair" | "poor" | "
  * accepts legacy alias tokens (`preorder` → `pre-order`, `product` → `standard`)
  * but stored values are always one of these five.
  */
-export type ListingType = "standard" | "auction" | "pre-order" | "prize-draw" | "classified" | "digital-code" | "live" | "art" | "stickers";
+export type ListingType = "standard" | "auction" | "pre-order" | "prize-draw" | "classified" | "digital-code" | "live" | "art" | "stickers" | "spares";
+/**
+ * One gallery image — THE single definition, used by both the Firestore
+ * document and the client shape.
+ *
+ * 🛑 This interface already existed here, barrel-exported as public API, with
+ * ZERO consumers anywhere and `Product.images` declared `string[]` beside it:
+ * a speculative type describing a shape nothing produced or read. Plan A6
+ * resurrected it rather than declaring a second `ProductImage` in
+ * `schemas/firestore.ts`, which is what the first draft did — two same-named
+ * types in one package is a defect even when both look plausible, and the
+ * barrel's choice between them is invisible at every call site (Root Cause
+ * #36). `schemas/firestore.ts` imports this one.
+ *
+ * `alt` is the point: measured across the fifteen-site competitor crawl,
+ * per-image alt coverage is ~0% (0/151, 0/306, 0/317; tcgrepublic's 37/63 is
+ * the best anyone manages). `width`/`height` let `next/image` reserve space so
+ * a gallery does not reflow as each image lands — optional because we do not
+ * always know them at write time, and a guessed aspect ratio is worse than
+ * none.
+ */
 export interface ProductImage {
     url: string;
     thumbnailUrl?: string;
     alt?: string;
     order?: number;
+    width?: number;
+    height?: number;
 }
 export interface ProductSeo {
     title?: string;
@@ -78,6 +100,28 @@ export interface ProductItem {
     sublistingIcon?: string;
     isOnSale?: boolean;
     isSold?: boolean;
+    /**
+     * Printed or built when ordered, so stock does not gate it. Per-LISTING, not
+     * implied by `listingType` — a seller can hold a finite run of pre-cut sheets
+     * and also offer a print-on-demand one.
+     *
+     * On the client this drives three things: the PDP says "made to order"
+     * instead of a stock line, the group picker uncaps that member's stepper, and
+     * `baseAvailable` keeps the row in the default scope at quantity 0.
+     */
+    madeToOrder?: boolean;
+    /**
+     * Self-assembled-selection rules, present only on a group PARENT. See
+     * `_internal/shared/features/products/group-rules.ts` for the shape, the
+     * resolver and the single enforcement point — these fields exist here only
+     * so the admin editor (`GroupSettingsPanel`'s `groupRules` prop) can seed its
+     * form from the product it is already showing, with no second fetch.
+     */
+    groupMinMembers?: number;
+    groupMaxMembers?: number;
+    groupMaxUnitsPerMember?: number;
+    groupRequiredMemberIds?: string[];
+    groupDiscountPercent?: number;
     inStock?: boolean;
     stockCount?: number;
     rating?: number;

package/dist/features/products/utils/group-member-image.d.ts

@@ -0,0 +1,46 @@
+import type { ProductImage } from "../schemas/firestore";
+/**
+ * The thumbnail for one product-group member, from whichever shape the caller
+ * supplied.
+ *
+ * ── 🛑 WHY `image` IS TRIED FIRST ──────────────────────────────────────────
+ *
+ * `toPublicGroupMember` is an ALLOW-LIST projection: it emits the singular
+ * `image` (`images[0].url ?? mainImage`) and no `images[]` array at all. So a
+ * component reading only `images[0]` resolves `undefined` for every member
+ * served by the public endpoint and renders a placeholder tile.
+ *
+ * That was live on every product-group page — all seven BX-53 members showed
+ * a grey box while their images sat in Storage serving HTTP 200. Nothing
+ * errors, because an empty `src` is a legal `MediaImage`.
+ *
+ * The `images[0]` fallback stays for callers that pass a raw document rather
+ * than the projection.
+ *
+ * ── 🛑 WHY ITS OWN MODULE, AND NOT EITHER COMPONENT ────────────────────────
+ *
+ * `ShowGroupSection` renders `GroupMemberPicker`, so the import edge between
+ * them already runs one way. Putting the shared helper in either file and
+ * importing it from the other closes a CYCLE — which is exactly what
+ * `audit-import-cycles` caught when the first version of this fix exported it
+ * from `ShowGroupSection`.
+ *
+ * A helper used by two components belongs beside neither (Root Cause #18:
+ * import from the module that DEFINES the symbol). One definition, two
+ * importers, no edge between them — and one rule reachable by copy-paste is
+ * one that gets copied wrong (Root Cause #75), which is how the two spellings
+ * diverged in the first place.
+ */
+export interface GroupMemberImageSource {
+    /** The public projection's single thumbnail. */
+    image?: string;
+    /**
+     * A raw document's gallery. Only read when `image` is absent.
+     *
+     * 🛑 `ProductImage[]` since A6 — a raw document holds objects, a legacy one
+     * holds strings, and the public projection holds neither. `productImageUrls`
+     * is the one normaliser that spans all three.
+     */
+    images?: readonly (string | ProductImage)[];
+}
+export declare function resolveGroupMemberImage(m: GroupMemberImageSource): string;

package/dist/features/products/utils/group-member-image.js

@@ -0,0 +1,4 @@
+import { productImageUrls } from "../schemas/firestore.js";
+export function resolveGroupMemberImage(m) {
+    return m.image || productImageUrls(m.images)[0] || "";
+}

package/dist/features/products/utils/listing-badge-variant.js

@@ -15,6 +15,10 @@ import { isListingType } from "./listing-type.js";
  */
 export const LISTING_BADGE_VARIANT = {
     standard: "default",
+    // Shares `primary` with art/stickers: all three are "a thing we make or
+    // salvage ourselves" rather than a mechanism (auction) or a promise
+    // (pre-order), and the badge LABEL is what distinguishes them.
+    spares: "primary",
     auction: "warning",
     "pre-order": "secondary",
     "prize-draw": "primary",

package/dist/features/reviews/components/ReviewsList.js

@@ -29,7 +29,7 @@ export function ReviewCard({ review, context = "general", className = "" }) {
     const showProductLink = context !== "listing" && !!productHref;
     const showProfileLink = !!profileHref;
     const hasFooter = showStoreLink || showProductLink || showProfileLink;
-    return (_jsxs(Stack, { padding: "5", shadow: "hover-md", className: `group h-full border border-neutral-200 transition ${className}`, rounded: "xl", surface: "default", children: [_jsxs(Link, { href: reviewHref, className: "flex flex-col flex-1 min-h-0", children: [_jsxs(Row, { align: "start", gap: "3", children: [review.userAvatar ? (_jsx(Div, { className: "relative h-9 w-9 flex-shrink-0", rounded: "full", overflow: "hidden", children: _jsx(MediaImage, { src: review.userAvatar, alt: displayName, size: "avatar" }) })) : (_jsx(Row, { textWeight: "medium", textSize: "sm", className: "h-9 w-9 flex-shrink-0 bg-neutral-200 text-[var(--appkit-color-text-muted)]", align: "center", justify: "center", rounded: "full", children: initials })), _jsxs(Div, { className: "flex-1 min-w-0", children: [_jsxs(Row, { wrap: true, gap: "sm", children: [_jsx(Span, { color: "inverse", weight: "medium", className: "text-[var(--appkit-color-text)] dark:", children: displayName }), review.verified && (_jsx(Span, { color: "success", surface: "success-surface", size: "xs", weight: "medium", rounded: "full", padding: "pill-xs", children: "Verified" })), date && (_jsx(Span, { size: "xs", color: "muted", children: date }))] }), _jsx(Div, { className: "mt-1", children: _jsx(StarRating, { value: review.rating, size: "sm", readOnly: true }) })] })] }), review.title && (_jsx(Heading, { color: "inverse", level: 4, className: "mt-3 text-[var(--appkit-color-text)] dark:", weight: "semibold", children: review.title })), review.comment && (_jsx(RichText, { html: normalizeRichTextHtml(review.comment), proseClass: "prose prose-sm max-w-none dark:prose-invert prose-p:my-0", className: "mt-2 text-[length:var(--appkit-text-sm)] leading-relaxed text-[var(--appkit-color-text-muted)] text-[var(--appkit-color-text-muted)]" })), review.images && review.images.length > 0 && (_jsx(Row, { wrap: true, gap: "sm", className: "mt-3", children: review.images.map((img, i) => (_jsx(Div, { className: "relative h-16 w-16 flex-shrink-0 border border-neutral-100", rounded: "lg", overflow: "hidden", children: _jsx(MediaImage, { src: img, alt: `Review image ${i + 1}`, size: "thumbnail" }) }, i))) })), (review.helpfulCount ?? 0) > 0 && (_jsxs(Text, { className: "mt-3", color: "faint", size: "xs", children: [review.helpfulCount, " found this helpful"] }))] }), hasFooter && (_jsxs(Stack, { gap: "xs", className: "mt-3 border-t border-neutral-100", padding: "t-sm", children: [showStoreLink && (_jsxs(Link, { href: String(ROUTES.PUBLIC.STORE_DETAIL(review.storeSlug)), className: "flex items-center gap-[var(--appkit-space-1-5)] text-[length:var(--appkit-text-xs)] font-medium text-primary hover:underline", children: [_jsx(Span, { "aria-hidden": "true", children: "\uD83C\uDFEA" }), _jsx(Span, { truncate: true, children: review.storeName })] })), showProductLink && (_jsxs(Link, { href: productHref, className: "flex items-center gap-[var(--appkit-space-1-5)] text-[length:var(--appkit-text-xs)] font-medium text-[var(--appkit-color-text-muted)] text-[var(--appkit-color-text-muted)] hover:text-neutral-700 hover:text-[var(--appkit-color-text-muted)]", children: [_jsx(Span, { "aria-hidden": "true", children: "\uD83D\uDCE6" }), _jsx(Span, { truncate: true, children: review.productTitle ?? "View Product" }), _jsx(Span, { "aria-hidden": "true", className: "ml-auto text-primary group-hover:translate-x-0.5 transition-transform", children: "\u2192" })] })), showProfileLink && (_jsxs(Link, { href: profileHref, className: "flex items-center gap-[var(--appkit-space-1-5)] text-[length:var(--appkit-text-xs)] font-medium text-[var(--appkit-color-text-muted)] text-[var(--appkit-color-text-muted)] hover:text-neutral-700 hover:text-[var(--appkit-color-text-muted)]", children: [_jsx(Span, { "aria-hidden": "true", children: "\uD83D\uDC64" }), _jsx(Span, { truncate: true, children: displayName })] }))] }))] }));
+    return (_jsxs(Stack, { padding: "5", shadow: "hover-md", className: `group h-full border border-neutral-200 transition ${className}`, rounded: "xl", surface: "default", children: [_jsxs(Link, { href: reviewHref, className: "flex flex-col flex-1 min-h-0", children: [_jsxs(Row, { align: "start", gap: "3", children: [review.userAvatar ? (_jsx(Div, { className: "relative h-9 w-9 flex-shrink-0", rounded: "full", overflow: "hidden", children: _jsx(MediaImage, { src: review.userAvatar, alt: displayName, size: "avatar" }) })) : (_jsx(Row, { textWeight: "medium", textSize: "sm", className: "h-9 w-9 flex-shrink-0 bg-neutral-200 text-[var(--appkit-color-text-muted)]", align: "center", justify: "center", rounded: "full", children: initials })), _jsxs(Div, { className: "flex-1 min-w-0", children: [_jsxs(Row, { wrap: true, gap: "sm", children: [_jsx(Span, { color: "inverse", weight: "medium", className: "text-[var(--appkit-color-text)] dark:", children: displayName }), review.verified && (_jsx(Span, { color: "success", surface: "success-surface", size: "xs", weight: "medium", rounded: "full", padding: "pill-xs", children: "Verified" })), date && (_jsx(Span, { size: "xs", color: "muted", children: date }))] }), _jsx(Div, { className: "mt-1", children: _jsx(StarRating, { value: review.rating, size: "sm", readOnly: true }) })] })] }), review.title && (_jsx(Heading, { color: "inverse", level: 4, className: "mt-3 text-[var(--appkit-color-text)] dark:", weight: "semibold", children: review.title })), review.comment && (_jsx(RichText, { html: normalizeRichTextHtml(review.comment), proseClass: "prose prose-sm max-w-none dark:prose-invert prose-p:my-0", className: "mt-2 text-[length:var(--appkit-text-sm)] leading-relaxed text-[var(--appkit-color-text-muted)] text-[var(--appkit-color-text-muted)]" })), review.images && review.images.length > 0 && (_jsx(Row, { wrap: true, gap: "sm", className: "mt-3", children: review.images.map((img, i) => (_jsx(Div, { className: "relative h-16 w-16 flex-shrink-0 border border-neutral-100", rounded: "lg", overflow: "hidden", children: _jsx(MediaImage, { src: img, alt: `Review image ${i + 1}`, size: "thumbnail" }) }, i))) })), (review.helpfulCount ?? 0) > 0 && (_jsxs(Text, { className: "mt-3", color: "faint", size: "xs", children: [review.helpfulCount, " found this helpful"] }))] }), hasFooter && (_jsxs(Stack, { gap: "xs", className: "mt-3 border-t border-neutral-100", padding: "t-sm", children: [showStoreLink && (_jsxs(Link, { href: String(ROUTES.PUBLIC.STORE_DETAIL(review.storeSlug)), className: "flex items-center gap-[var(--appkit-space-1-5)] text-[length:var(--appkit-text-xs)] font-medium text-primary hover:underline", children: [_jsx(Span, { "aria-hidden": "true", children: "\uD83C\uDFEA" }), _jsx(Span, { truncate: true, children: review.storeName })] })), showProductLink && (_jsxs(Link, { href: productHref, className: "flex items-center gap-[var(--appkit-space-1-5)] text-[length:var(--appkit-text-xs)] font-medium text-[var(--appkit-color-text-muted)] hover:text-[var(--appkit-color-text)]", children: [_jsx(Span, { "aria-hidden": "true", children: "\uD83D\uDCE6" }), _jsx(Span, { truncate: true, children: review.productTitle ?? "View Product" }), _jsx(Span, { "aria-hidden": "true", className: "ml-auto text-primary group-hover:translate-x-0.5 transition-transform", children: "\u2192" })] })), showProfileLink && (_jsxs(Link, { href: profileHref, className: "flex items-center gap-[var(--appkit-space-1-5)] text-[length:var(--appkit-text-xs)] font-medium text-[var(--appkit-color-text-muted)] hover:text-[var(--appkit-color-text)]", children: [_jsx(Span, { "aria-hidden": "true", children: "\uD83D\uDC64" }), _jsx(Span, { truncate: true, children: displayName })] }))] }))] }));
 }
 export function ReviewsList({ reviews, context = "general", isLoading, totalPages = 1, currentPage = 1, onPageChange, emptyLabel = "No reviews yet", }) {
     if (isLoading) {

package/dist/features/scams/components/ScamProfileView.js

@@ -51,7 +51,7 @@ export function ScamProfileView({ scammer, isAuthenticated, incidents = [], comm
     const registryHref = String(ROUTES.PUBLIC.SCAMS);
     const contestLoginHref = `${String(ROUTES.AUTH.LOGIN)}?redirect=${encodeURIComponent(`/scams/${scammer.id}`)}`;
     const scamTypeDef = getScamType(scammer.scamType);
-    return (_jsxs(Main, { children: [_jsx(Div, { className: "border-b appkit-breadcrumb-strip", children: _jsx(Container, { size: "xl", padding: "y-sm", children: _jsx(Breadcrumb, { items: [
+    return (_jsxs(Main, { children: [_jsx(Div, { className: "border-b", children: _jsx(Container, { size: "xl", padding: "y-sm", children: _jsx(Breadcrumb, { items: [
                             { label: "Home", href: "/" },
                             { label: "Scam Registry", href: registryHref },
                             { label: scammer.displayNames[0] ?? "Profile" },

package/dist/features/search/components/EntityTypeahead.d.ts

@@ -0,0 +1,44 @@
+import React from "react";
+export interface EntityTypeaheadPick {
+    /** The canonical entity's title, as the index holds it. */
+    readonly title: string;
+    /** Its destination, which encodes the slug. */
+    readonly href: string;
+    /** The index type it came from. */
+    readonly typeKey: string;
+    /**
+     * 🛑 What the USER typed, verbatim. See the header — a consumer that
+     * analyses the resolved title instead of this is throwing away the signal
+     * it was built to detect.
+     */
+    readonly rawQuery: string;
+}
+export interface EntityTypeaheadProps {
+    /** Index type keys to search. `["model"]`, `["category"]`, `["part"]`… */
+    types: readonly string[];
+    onPick: (pick: EntityTypeaheadPick) => void;
+    /** `siteSettings.search?.indexEnabled`. Read as `!== false`. */
+    indexEnabled?: boolean;
+    label: string;
+    placeholder?: string;
+    /** Mirrors the field the consumer owns, so the two cannot disagree. */
+    value?: string;
+    onChange?: (value: string) => void;
+    limit?: number;
+    /**
+     * Default `true`: picking a suggestion fills the field with the
+     * canonical title, as every ordinary typeahead does.
+     *
+     * 🛑 Set `false` when the consumer's DOWNSTREAM LOGIC treats a mismatch
+     * between what was typed and the canonical form as a signal rather than
+     * noise — `/tools/authenticity` is the one caller that needs this. Its
+     * engine fires a trademark-evasion warning on a FUZZY match, and that
+     * warning is exactly what filling the field would silence: the engine
+     * would receive "Storm Pegasus" and match it exactly, never learning the
+     * user typed "Pegasis" at all. With this false, a pick still calls
+     * `onPick` (with `rawQuery` intact) but leaves the field exactly as
+     * typed — discovery without consequence.
+     */
+    fillOnPick?: boolean;
+}
+export declare function EntityTypeahead({ types, onPick, indexEnabled, label, placeholder, value, onChange, limit, fillOnPick, }: EntityTypeaheadProps): React.JSX.Element;

package/dist/features/search/components/EntityTypeahead.js

@@ -0,0 +1,92 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/*
+ * WHY: Three tools need "turn what the user typed into a canonical entity",
+ *      and each wants a different slice. `resolveEntity`'s `types` parameter
+ *      exists for exactly this; this is its UI.
+ * WHAT: A generic index-backed typeahead. Offers canonical names, reports
+ *       BOTH the chosen entity and the raw string the user typed.
+ *
+ * ## 🛑 `onPick` hands back the RAW query as well as the entity
+ *
+ * This is the one thing about the component that is not a convenience.
+ *
+ * `/tools/authenticity` treats a fuzzy name match as EVIDENCE — a near-miss
+ * fires a trademark-evasion warning, and its own source records the case:
+ * "`Pegasis` … resolves as an `alias` hit, and the evasion-spelling warning
+ * (which only fires on a `fuzzy` hit) stays silent." Meanwhile this
+ * component's matcher derives its alias table from a crawl of a counterfeit
+ * seller's 1,277 titles, on the stated insight that "a counterfeiter's
+ * evasion spellings are the same strings a real buyer mistypes."
+ *
+ * Both systems consume the same corpus with OPPOSITE intent: search treats a
+ * counterfeiter's spelling as something to match through, authenticity
+ * treats it as the signal. So if someone types `Pegasis`, picks "Storm
+ * Pegasus" from this dropdown, and the consumer forwards only the resolved
+ * slug, the engine never sees `Pegasis` and the evasion warning is silenced
+ * BY CONSTRUCTION — the tool would confirm a fake using the exact spelling
+ * that indicates one.
+ *
+ * Hence: this component PROPOSES an entity; the consumer must keep passing
+ * what the user actually typed. Enforced from the other side by
+ * `audit-entity-resolver-consumers` R2, which forbids any module under
+ * `features/authenticity/` from importing the matcher at all — which is why
+ * this lives here and reaches that tool as a slot.
+ *
+ * @tag domain:search
+ * @tag layer:feature
+ * @tag pattern:none
+ * @tag access:client
+ * @tag consumers:/tools/authenticity,/tools/price-index
+ * @tag sideEffects:network
+ */
+import React from "react";
+import { Button, Div, Input, Stack, Text } from "../../../ui/index.js";
+import { useSiteSearch } from "../hooks/useSiteSearch.js";
+/** Stable identity — a `useMemo` dependency inside the hook. */
+const passthroughLabel = (typeKey) => typeKey;
+export function EntityTypeahead({ types, onPick, indexEnabled, label, placeholder, value, onChange, limit = 6, fillOnPick = true, }) {
+    const controlled = value !== undefined;
+    const [internal, setInternal] = React.useState("");
+    const query = controlled ? value : internal;
+    const [active, setActive] = React.useState(false);
+    const [dismissed, setDismissed] = React.useState(false);
+    const { status, result } = useSiteSearch(query, {
+        active,
+        indexEnabled,
+        types,
+        label: passthroughLabel,
+    });
+    const hits = result?.groups.flatMap((g) => g.hits) ?? [];
+    const show = !dismissed && status === "ready" && hits.length > 0 && query.trim().length > 0;
+    const setQuery = (next) => {
+        setDismissed(false);
+        if (controlled)
+            onChange?.(next);
+        else
+            setInternal(next);
+    };
+    return (_jsxs(Stack, { gap: "xs", className: "min-w-0", children: [_jsx(Input, { type: "search", value: query, "aria-label": label, placeholder: placeholder, onFocus: () => setActive(true), onChange: (event) => {
+                    setActive(true);
+                    setQuery(event.target.value);
+                } }), show && (_jsxs(Stack, { gap: "xs", className: "min-w-0", children: [_jsx(Text, { size: "xs", color: "muted", children: "Did you mean one of these?" }), hits.slice(0, limit).map((hit) => (_jsxs(Div, { surface: "card", padding: "xs", rounded: "md", border: "subtle", children: [_jsx(Button, { variant: "ghost", size: "sm", onClick: () => {
+                                    /*
+                                     * 🛑 `rawQuery: query` — BEFORE the field is overwritten
+                                     * with the canonical title. Reading it after would hand the
+                                     * consumer the canonical name as "what the user typed",
+                                     * which is the silent version of the bug this whole
+                                     * component's header is about.
+                                     */
+                                    onPick({
+                                        title: hit.title,
+                                        href: hit.href,
+                                        typeKey: result?.groups.find((g) => g.hits.includes(hit))?.key ?? "",
+                                        rawQuery: query,
+                                    });
+                                    // See `fillOnPick`'s 🛑 — skipping this is the whole
+                                    // reason the prop exists, not an inconsistency.
+                                    if (fillOnPick)
+                                        setQuery(hit.title);
+                                    setDismissed(true);
+                                }, children: hit.title }), hit.detail && (_jsx(Text, { size: "xs", color: "muted", children: hit.detail }))] }, hit.id)))] }))] }));
+}

package/dist/features/search/components/Search.d.ts

@@ -47,5 +47,16 @@ export interface SearchProps {
     resourceTypes?: SearchResourceTypeOption[];
     defaultResourceType?: SearchResourceType;
     storageKey?: string;
+    /**
+     * `siteSettings.search?.indexEnabled`. Read as `!== false`, so an absent
+     * settings object leaves the local index in play.
+     *
+     * When the index answers, the typeahead spends ZERO network requests per
+     * keystroke and spans all 21 indexed types instead of the four
+     * `/api/search/suggestions` can produce. When it is off or has failed, the
+     * component falls back to that endpoint unchanged — which is why
+     * `useNavSuggestions` is still called rather than deleted.
+     */
+    searchIndexEnabled?: boolean;
 }
-export declare function Search({ isOpen, onClose, onSearch, onOpen, value, onChange, placeholder, deferred, debounceMs, onClear, className, router, quickLinks, labels, suggestionTypeIcons, suggestionTypeBadges, resourceTypes, defaultResourceType, storageKey, }: SearchProps): React.JSX.Element | null;
+export declare function Search({ isOpen, onClose, onSearch, onOpen, value, onChange, placeholder, deferred, debounceMs, onClear, className, router, quickLinks, labels, suggestionTypeIcons, suggestionTypeBadges, resourceTypes, defaultResourceType, storageKey, searchIndexEnabled, }: SearchProps): React.JSX.Element | null;