@mohasinac/appkit 4.53.0 → 4.53.1

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

@@ -2,7 +2,8 @@
  * Products Firestore Document Types & Constants
  */
 import { type GenerateProductIdInput, type GenerateAuctionIdInput, type GeneratePreOrderIdInput } from "../../../utils/id-generators";
-import type { ProductStatus, ListingType } from "../types";
+import type { ProductStatus, ListingType, ProductImage } from "../types";
+export type { ProductImage };
 import type { BaseDocument } from "../../../_internal/shared/types/base-document";
 import type { LotteryConfig } from "../../lottery/types";
 export interface ProductVideoField {
@@ -12,6 +13,31 @@ export interface ProductVideoField {
     trimStart?: number;
     trimEnd?: number;
 }
+/**
+ * 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 declare function toProductImages(input: unknown): ProductImage[];
+/**
+ * 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 declare function productImageUrls(input: unknown): string[];
 export interface ProductSpecification {
     name: string;
     value: string;
@@ -256,7 +282,14 @@ export interface ProductDocument extends BaseDocument {
     stockQuantity: number;
     availableQuantity: number;
     mainImage: string;
-    images: string[];
+    /**
+     * 🛑 `ProductImage[]`, not `string[]` (changed 2026-10-20, plan A6).
+     *
+     * Normalised by `toProductImages()` on BOTH the write path and `mapDoc`, so
+     * a legacy `string[]` document widens losslessly and a new write stores the
+     * object form. Call sites that only want URLs use `productImageUrls()`.
+     */
+    images: ProductImage[];
     video?: ProductVideoField;
     status: ProductStatus;
     storeId: string;
@@ -449,6 +482,52 @@ export interface ProductDocument extends BaseDocument {
     isPromoted?: boolean;
     isOnSale?: boolean;
     isSold?: boolean;
+    /**
+     * This listing is PRINTED OR BUILT WHEN ORDERED, so stock does not gate it.
+     *
+     * A per-LISTING flag, deliberately not implied by `listingType`. A seller can
+     * hold a finite run of pre-cut sticker sheets and also offer a
+     * print-on-demand sheet, and the two must coexist on the same type — which a
+     * type-level rule cannot express. (`showsStockQuantity` on the plugin is the
+     * type-level field and must NOT be repurposed for this.)
+     *
+     * 🛑 It bypasses the stock CHECK and never the DECREMENT. `availableQuantity`
+     * going negative on a made-to-order row IS the production queue — how many
+     * are owed — and `stock-restore.ts` requires the restore to mirror the
+     * decrement exactly, so skipping the decrement would make a cancelled order
+     * restore stock that was never taken.
+     *
+     * 🛑 Not snapshotted onto `CartLineMember`. A snapshot goes stale the moment
+     * the flag is flipped, and every check site already holds the product
+     * document — so it is derived, never copied (Root Cause #42).
+     *
+     * 🛑 CHECKED, not assumed: nothing auto-sets `isSold` when quantity reaches
+     * zero, so a made-to-order listing does NOT destroy itself on its first
+     * sale. `buildStockUpdatePayload` writes `availableQuantity` and the rule's
+     * `stockDecrementExtras` and nothing else; the only two writers of
+     * `isSold: true` in the whole tree are auction settlement and the auction
+     * buyout, both of which are selling a unique lot and are correct to do it.
+     * If a future "mark sold out automatically" feature is added, it must skip
+     * made-to-order rows or every one of them dies on its first order.
+     */
+    madeToOrder?: boolean;
+    /**
+     * The `stickerSheets` document this listing was promoted from.
+     *
+     * Set on BOTH the parent (the whole sheet) and every child (one cut), so the
+     * relationship is answerable from either end without a query — "which sheet
+     * is this sticker off" and "has this sheet already been promoted" are both
+     * questions the admin UI asks.
+     */
+    sourceStickerSheetId?: string;
+    /**
+     * Which cut of that sheet, by `SheetPart.ordinal`.
+     *
+     * 🛑 The ordinal, never an array index — `parts[]` is not guaranteed dense or
+     * ordered and a re-promote rewrites it, so an index would silently point at a
+     * different sticker. Absent on the parent, which is the whole sheet.
+     */
+    sourceStickerPartOrdinal?: number;
     /** When true, an EMI order for this product ships as soon as it's confirmed instead of waiting for every installment to be paid. Default false. */
     allowShipBeforeEmiComplete?: boolean;
     /**
@@ -514,6 +593,20 @@ export interface ProductDocument extends BaseDocument {
     groupParentSlug?: string;
     groupChildSlugs?: string[];
     groupTitle?: string;
+    groupMinMembers?: number;
+    groupMaxMembers?: number;
+    groupMaxUnitsPerMember?: number;
+    groupRequiredMemberIds?: string[];
+    /**
+     * Percentage off a self-assembled selection's subtotal, 0–100.
+     *
+     * 🛑 Applied in exactly ONE place: the repository's private
+     * `deriveLinePrice`, which runs on every `groupMembers` write and feeds
+     * `expandCartLineToOrderRows`' per-member GST proration through
+     * `allocateAcrossMembers`. A second application anywhere makes the cart total
+     * disagree with the invoice (Root Cause #75).
+     */
+    groupDiscountPercent?: number;
     /**
      * W1-45 — optional icon shown as an overlay badge on every card whose
      * product belongs to this group. Set once on the group parent; cards
@@ -683,8 +776,8 @@ export declare const ProductStatusValues: {
 export declare const PRODUCT_COLLECTION: "products";
 export declare const PRODUCT_INDEXED_FIELDS: readonly ["storeId", "status", "category", "categoryIds", "featured", "listingType", "isPromoted", "isOnSale", "isSold", "searchTxt", "createdAt", "barcodeId", "physicalLocation.zone"];
 export declare const DEFAULT_PRODUCT_DATA: Partial<ProductDocument>;
-export declare const PRODUCT_PUBLIC_FIELDS: readonly ["allowOffers", "minOfferPercent", "id", "title", "description", "category", "categoryIds", "categoryIdNames", "subcategory", "brand", "price", "originalPrice", "currency", "stockQuantity", "availableQuantity", "images", "status", "storeName", "featured", "tags", "specifications", "features", "shippingInfo", "returnPolicy", "finalSale", "isLot", "lotSize", "unitLabel", "partGlossaryId", "colourway", "mouldVariant", "assembledFrom", "views7d", "views30d", "unitLabel", "partGlossaryId", "colourway", "mouldVariant", "assembledFrom", "listingType", "auctionEndDate", "startingBid", "currentBid", "bidCount", "reservePrice", "buyNowPrice", "minBidIncrement", "autoExtendable", "auctionExtensionMinutes", "auctionShippingPaidBy", "bidsHaveStarted", "grading", "card", "classified", "digitalCode", "liveItem", "catalogProductId", "preOrderDeliveryDate", "preOrderDepositPercent", "preOrderDepositAmount", "preOrderMaxQuantity", "preOrderCurrentCount", "preOrderProductionStatus", "preOrderCancellable", "condition", "insurance", "insuranceCost", "shippingPaidBy", "isPromoted", "isOnSale", "isSold", "slug", "seoTitle", "seoDescription", "seoKeywords", "viewCount", "customFields", "customSections", "sublistingCategoryId", "groupId", "isGroupParent", "groupParentSlug", "groupChildSlugs", "groupTitle", "createdAt"];
-export declare const PRODUCT_UPDATABLE_FIELDS: readonly ["title", "description", "category", "categoryIds", "subcategory", "brand", "price", "originalPrice", "stockQuantity", "images", "status", "tags", "specifications", "features", "shippingInfo", "returnPolicy", "finalSale", "isLot", "lotSize", "pickupAddressId", "condition", "insurance", "shippingPaidBy", "autoExtendable", "auctionExtensionMinutes", "auctionShippingPaidBy", "reservePrice", "buyNowPrice", "minBidIncrement", "bidsHaveStarted", "grading", "card", "classified", "digitalCode", "liveItem", "catalogProductId", "listingType", "preOrderDeliveryDate", "preOrderDepositPercent", "preOrderDepositAmount", "preOrderMaxQuantity", "preOrderProductionStatus", "preOrderCancellable", "isOnSale", "isSold", "allowShipBeforeEmiComplete", "gstRate", "hsnCode", "authenticity", "printMeta", "seoTitle", "seoDescription", "seoKeywords", "customFields", "customSections", "sublistingCategoryId", "groupId", "isGroupParent", "groupParentSlug", "groupChildSlugs", "groupTitle", "barcodeId"];
+export declare const PRODUCT_PUBLIC_FIELDS: readonly ["allowOffers", "minOfferPercent", "id", "title", "description", "category", "categoryIds", "categoryIdNames", "subcategory", "brand", "price", "originalPrice", "currency", "stockQuantity", "availableQuantity", "images", "status", "storeName", "featured", "tags", "specifications", "features", "shippingInfo", "returnPolicy", "finalSale", "isLot", "lotSize", "unitLabel", "partGlossaryId", "colourway", "mouldVariant", "assembledFrom", "views7d", "views30d", "unitLabel", "partGlossaryId", "colourway", "mouldVariant", "assembledFrom", "listingType", "auctionEndDate", "startingBid", "currentBid", "bidCount", "reservePrice", "buyNowPrice", "minBidIncrement", "autoExtendable", "auctionExtensionMinutes", "auctionShippingPaidBy", "bidsHaveStarted", "grading", "card", "classified", "digitalCode", "liveItem", "catalogProductId", "preOrderDeliveryDate", "preOrderDepositPercent", "preOrderDepositAmount", "preOrderMaxQuantity", "preOrderCurrentCount", "preOrderProductionStatus", "preOrderCancellable", "condition", "insurance", "insuranceCost", "shippingPaidBy", "isPromoted", "isOnSale", "isSold", "madeToOrder", "sourceStickerSheetId", "sourceStickerPartOrdinal", "slug", "seoTitle", "seoDescription", "seoKeywords", "viewCount", "customFields", "customSections", "sublistingCategoryId", "groupId", "isGroupParent", "groupParentSlug", "groupChildSlugs", "groupTitle", "groupMinMembers", "groupMaxMembers", "groupMaxUnitsPerMember", "groupRequiredMemberIds", "groupDiscountPercent", "createdAt"];
+export declare const PRODUCT_UPDATABLE_FIELDS: readonly ["title", "description", "category", "categoryIds", "subcategory", "brand", "price", "originalPrice", "stockQuantity", "images", "status", "tags", "specifications", "features", "shippingInfo", "returnPolicy", "finalSale", "isLot", "lotSize", "pickupAddressId", "condition", "insurance", "shippingPaidBy", "autoExtendable", "auctionExtensionMinutes", "auctionShippingPaidBy", "reservePrice", "buyNowPrice", "minBidIncrement", "bidsHaveStarted", "grading", "card", "classified", "digitalCode", "liveItem", "catalogProductId", "listingType", "preOrderDeliveryDate", "preOrderDepositPercent", "preOrderDepositAmount", "preOrderMaxQuantity", "preOrderProductionStatus", "preOrderCancellable", "isOnSale", "isSold", "madeToOrder", "sourceStickerSheetId", "sourceStickerPartOrdinal", "allowShipBeforeEmiComplete", "gstRate", "hsnCode", "authenticity", "printMeta", "seoTitle", "seoDescription", "seoKeywords", "customFields", "customSections", "sublistingCategoryId", "groupId", "isGroupParent", "groupParentSlug", "groupChildSlugs", "groupTitle", "groupMinMembers", "groupMaxMembers", "groupMaxUnitsPerMember", "groupRequiredMemberIds", "groupDiscountPercent", "barcodeId"];
 export type ProductCreateInput = Omit<ProductDocument, "id" | "createdAt" | "updatedAt" | "availableQuantity" | "bidCount" | "currentBid" | "auctionOriginalEndDate">;
 export type ProductUpdateInput = Partial<Pick<ProductDocument, (typeof PRODUCT_UPDATABLE_FIELDS)[number]>>;
 export type ProductAdminUpdateInput = Partial<Omit<ProductDocument, "id" | "createdAt">>;

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,39 @@
+/**
+ * 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. */
+    images?: string[];
+}
+export declare function resolveGroupMemberImage(m: GroupMemberImageSource): string;

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

@@ -0,0 +1,3 @@
+export function resolveGroupMemberImage(m) {
+    return m.image ?? 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;