@mohasinac/appkit 4.43.0 → 4.45.0

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

@@ -124,13 +124,37 @@ export interface ProductPrintMeta {
     /** Limited-edition print run size; omitted for open editions. */
     editionSize?: number;
 }
+/**
+ * Licensed manufacture vs. an unbranded 1st copy vs. not established.
+ *
+ * 🛑 THERE IS NO "fake" VALUE, and that is a product decision rather than an
+ * omission. A poor-quality counterfeit — BAS's own buying guide names cadmium
+ * and lead in the metal parts — is not a listing state we offer. It is a
+ * report, and it belongs in the scam registry, which already has 27 scam
+ * types and an evidence model.
+ *
+ * "reproduction" is the midfake tier: largely Chinese, no manufacturer's
+ * marque, generally decent quality, and some WBO formats permit certain repro
+ * parts — so it is sellable WHEN LABELLED. "unverified" exists because the
+ * alternative is far worse: without it, an honest seller who does not know
+ * would have to pick "original", and silence would be indistinguishable from
+ * a genuine claim.
+ *
+ * 🛑 And the buyer-facing framing to design against is NOT "fake". The
+ * counterfeit seller in the crawl makes no authenticity claim at all — zero
+ * occurrences of original/Takara/authentic/replica/fake across 1,277 products
+ * — and sells itself as an "aftermarket brand" with "upgraded components".
+ * "Aftermarket" and "custom" are the words our buyers will be sold, so the
+ * help copy has to answer that, not a word nobody uses.
+ */
+export type ProductAuthenticity = "original" | "reproduction" | "unverified";
 export interface ProductDocument extends BaseDocument {
     title: string;
     description: string;
     slug?: string;
-    /** Tester sandbox flag — set on shared admin-seeded test products; swept by testerSandboxCleanup. */
+    /** Test-data flag — set on shared admin-seeded test products; swept by testDataCleanup. */
     isTestData?: boolean;
-    /** When isTestData, the cutoff after which testerSandboxCleanup deletes this doc (cascades to bids). */
+    /** When isTestData, the cutoff after which testDataCleanup deletes this doc (cascades to bids). */
     testDataExpiresAt?: Date;
     seoTitle?: string;
     seoDescription?: string;
@@ -251,10 +275,46 @@ export interface ProductDocument extends BaseDocument {
     isSold?: boolean;
     /** 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;
-    /** P-8 GST — buyer-facing tax rate on this product (%). Unset/0 = exempt. */
+    /**
+     * P-8 GST — buyer-facing tax rate on this product (%).
+     *
+     * 🛑 `undefined` and `0` MEAN DIFFERENT THINGS. Zero is a deliberate
+     * exemption (live plants and animals); undefined is "nobody has said".
+     * So the test is `== null`, NEVER `input.gstRate || default`, which would
+     * silently overwrite every exempt row with the default rate. And there is
+     * deliberately no entry for this in `DEFAULT_PRODUCT_DATA` — a default
+     * there makes `undefined` unreachable in new rows while existing rows
+     * still lack it, which is the `finalSale` trap one field over.
+     *
+     * Written by `deriveTaxonomy` from the category's `taxCodeId`, but the
+     * SCALAR is what every reader and the order-item snapshot use: a tax-code
+     * edit must change future derivations, never retroactively re-rate an
+     * invoice already issued.
+     */
     gstRate?: 0 | 5 | 12 | 18 | 28;
-    /** P-8 GST — Harmonized System of Nomenclature code for GST-compliant invoices. */
+    /** P-8 GST — HSN code for GST-compliant invoices. Resolved alongside `gstRate`. */
     hsnCode?: string;
+    /**
+     * WHO MADE IT — distinct from `condition` (how worn) and from `brand`
+     * (whose marque is on it, which a reproduction has none of). The two axes
+     * are independent: an original can be broken and a reproduction can be
+     * mint.
+     *
+     * 🛑 This is BOTH a field and a feature, deliberately, and it is the only
+     * place in this schema where that duplication is justified. Structurally
+     * it is a classifier and belongs in the `authenticity` FeatureGroup — but
+     * a feature can be OMITTED and nothing notices. A mislabelled
+     * reproduction is a refund; a mislabelled counterfeit is a child handling
+     * leaded metal. The enum makes the question unskippable and writes the
+     * matching feature, so the facet, the badge and search all read one
+     * vocabulary.
+     *
+     * Validated by the competitor crawl: worldhobbyshop ships a nav category
+     * called "MidFake Beyblades" and an FAQ promising that authenticity and
+     * condition are both disclosed per listing. Hence "Midfake" as the LABEL
+     * on the reproduction tier — it is the word buyers search.
+     */
+    authenticity?: ProductAuthenticity;
     /** Print-specific metadata for "art" / "stickers" listings — printed-only physical goods. Optional on every listing type; only populated for art/stickers. */
     printMeta?: ProductPrintMeta;
     promotionEndDate?: Date;
@@ -377,6 +437,31 @@ export interface ProductDocument extends BaseDocument {
             etaDaysMax?: number;
         }>;
     };
+    /**
+     * The PACKED parcel — C5a. Optional on purpose.
+     *
+     * 🛑 The figure a carrier bills on is the packed box, not the item: a bey is
+     * ~30 g and ~300 g boxed. A REQUIRED product weight would therefore be an
+     * item weight that systematically under-estimates every booking — and
+     * because a booking is capped at the amount collected from the buyer,
+     * systematic under-estimation means silently absorbing the difference on
+     * every order.
+     *
+     * So three tiers: the category's packed default drives the checkout
+     * estimate, this refines it when a seller has actually weighed a box, and
+     * the real figure is entered at shipment time. See
+     * `_internal/shared/features/shipping/parcel.ts`.
+     *
+     * `dimensionsCm` is all three or nothing — a box with a length and no width
+     * is not a dimension, and a volumetric calculation fed two of three yields a
+     * quote for a flat sheet.
+     */
+    weightG?: number;
+    dimensionsCm?: {
+        l: number;
+        w: number;
+        h: number;
+    };
     /** Physical storage location for inventory management (Print & Label Center). */
     physicalLocation?: {
         zone: string;
@@ -420,10 +505,10 @@ export declare const ProductStatusValues: {
     readonly ARCHIVED: "archived";
 };
 export declare const PRODUCT_COLLECTION: "products";
-export declare const PRODUCT_INDEXED_FIELDS: readonly ["storeId", "status", "category", "featured", "listingType", "isPromoted", "isOnSale", "isSold", "searchTxt", "createdAt", "barcodeId"];
+export declare const PRODUCT_INDEXED_FIELDS: readonly ["storeId", "status", "category", "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", "subcategory", "brand", "price", "currency", "stockQuantity", "availableQuantity", "images", "status", "storeName", "featured", "tags", "specifications", "features", "shippingInfo", "returnPolicy", "finalSale", "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", "subcategory", "brand", "price", "stockQuantity", "images", "status", "tags", "specifications", "features", "shippingInfo", "returnPolicy", "finalSale", "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", "printMeta", "seoTitle", "seoDescription", "seoKeywords", "customFields", "customSections", "sublistingCategoryId", "groupId", "isGroupParent", "groupParentSlug", "groupChildSlugs", "groupTitle", "barcodeId"];
+export declare const PRODUCT_UPDATABLE_FIELDS: readonly ["title", "description", "category", "subcategory", "brand", "price", "stockQuantity", "images", "status", "tags", "specifications", "features", "shippingInfo", "returnPolicy", "finalSale", "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 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

@@ -1,7 +1,7 @@
 /**
  * Products Firestore Document Types & Constants
  */
-import { generateProductId, generateAuctionId, generatePreOrderId, } from "../../../utils/id-generators";
+import { generateProductId, generateAuctionId, generatePreOrderId, } from "../../../utils/id-generators.js";
 export const MAX_CUSTOM_FIELDS = 50;
 export const MAX_CUSTOM_SECTIONS = 3;
 /** Runtime-accessible product status values — use instead of bare string literals. */
@@ -24,6 +24,23 @@ export const PRODUCT_INDEXED_FIELDS = [
     "searchTxt",
     "createdAt",
     "barcodeId",
+    /*
+     * The warehouse location — C4.
+     *
+     * 🛑 A single-field entry, deliberately, and the distinction matters.
+     * Firestore indexes single fields automatically, so this list is
+     * documentation of what the collection is QUERIED by rather than the
+     * mechanism — and the real answer for location is `searchTxt`, which is
+     * already here. Listing the nested paths records that they are now a
+     * supported query shape (the Sieve config accepts them), so the next person
+     * adding a composite sees them rather than discovering a dropped clause.
+     *
+     * `physicalLocation.zone` is the only part worth naming: a zone is the
+     * coarse bucket a dashboard groups by, while shelf and bin are what search
+     * resolves. Naming all three would imply three query shapes exist when one
+     * does.
+     */
+    "physicalLocation.zone",
 ];
 export const DEFAULT_PRODUCT_DATA = {
     status: "draft",
@@ -173,6 +190,15 @@ export const PRODUCT_UPDATABLE_FIELDS = [
     "isOnSale",
     "isSold",
     "allowShipBeforeEmiComplete",
+    /*
+     * B3 — these three were MISSING, so the fields existed on the document
+     * and were not type-legal to update: ProductUpdateInput is derived from
+     * this list, so an admin or seller form could accept a GST rate and the
+     * repository would refuse to write it.
+     */
+    "gstRate",
+    "hsnCode",
+    "authenticity",
     "printMeta",
     "seoTitle",
     "seoDescription",

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

@@ -459,10 +459,10 @@ export declare const productItemSchema: z.ZodObject<{
     }[] | undefined;
     prizeGithubFileUrl?: string | undefined;
     inStock?: boolean | undefined;
-    attributes?: Record<string, string> | undefined;
     originalPrice?: number | undefined;
     sellerAvatar?: string | undefined;
     stockCount?: number | undefined;
+    attributes?: Record<string, string> | undefined;
 }, {
     status: "published" | "draft" | "in_review" | "archived";
     id: string;
@@ -598,10 +598,10 @@ export declare const productItemSchema: z.ZodObject<{
     }[] | undefined;
     prizeGithubFileUrl?: string | undefined;
     inStock?: boolean | undefined;
-    attributes?: Record<string, string> | undefined;
     originalPrice?: number | undefined;
     sellerAvatar?: string | undefined;
     stockCount?: number | undefined;
+    attributes?: Record<string, string> | undefined;
 }>;
 /** Base Zod schema for list-query parameters. */
 export declare const productListParamsSchema: z.ZodObject<{

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

@@ -1,7 +1,7 @@
-export * from "./firestore";
+export * from "./firestore.js";
 import { z } from "zod";
-import { mediaFieldSchema } from "../../media/types/index";
-import { PRIZE_DRAW_DURATION_DAYS_MIN, PRIZE_DRAW_DURATION_DAYS_MAX, } from "../../../_internal/shared/checkout/rules/_limits";
+import { mediaFieldSchema } from "../../media/types/index.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({
     url: z.string(),

package/dist/features/products/schemas/product-features.d.ts

@@ -17,7 +17,22 @@
 export declare const PRODUCT_FEATURES_COLLECTION: "productFeatures";
 export declare const PRODUCT_FEATURE_PREFIX: "feature-";
 export declare const MAX_STORE_CUSTOM_FEATURES = 20;
-export declare const MAX_FEATURES_PER_PRODUCT = 10;
+/**
+ * Hard cap on `product.features[].length`.
+ *
+ * 🛑 RAISED 10 → 24 (B3). Ten was sized for *badges* — a handful of
+ * "Free Shipping"-style trust marks. This collection is now the platform's one
+ * controlled VOCABULARY (`tags` is retired), and a single realistic listing
+ * spends six before anything optional: a reproduction, new-in-box,
+ * japan-import, attack-type, right-spin, limited-release bey. A TCG single
+ * adds language + format + grade on top.
+ *
+ * 24 rather than unbounded because `features[]` is `array-contains`-indexed and
+ * feeds `buildProductSearchTxt`, which truncates at 600 tokens SILENTLY — an
+ * unbounded feature list would quietly evict real title/description tokens
+ * from the search index.
+ */
+export declare const MAX_FEATURES_PER_PRODUCT = 24;
 export type ProductFeatureScope = "platform" | "store";
 export type ProductFeatureCategory = "shipping" | "seller" | "condition" | "platform" | "auction" | "preorder" | "custom";
 export type ProductFeatureProductType = "product" | "auction" | "preorder" | "prize-draw" | "classified" | "digital-code" | "live" | "art" | "stickers" | "all";
@@ -27,6 +42,90 @@ export type ProductFeatureProductType = "product" | "auction" | "preorder" | "pr
  */
 export type ProductFeatureIcon = string;
 export declare function isFeatureIconPath(icon: string): boolean;
+/**
+ * The vocabulary's namespace.
+ *
+ * 🛑 NOT the same axis as `category` above, which groups features by the
+ * SURFACE that shows them (shipping/seller/platform/auction/preorder) and is
+ * what drives badge placement. `group` namespaces what a feature MEANS, and
+ * drives the filter drawer: one facet section per group, rather than one flat
+ * 60-value checkbox list.
+ *
+ * Namespacing is load-bearing because **the same word means different things
+ * per vertical**: "sealed" on a TCG booster box is a factory seal, on a bey it
+ * is an unopened blister; "premium" is a Hot Wheels sub-line, not a quality
+ * claim. A single flat vocabulary would have to pick one meaning.
+ *
+ * Values derived from the measured competitor crawl — see
+ * `docs/research/competitor-crawl-2026-10/vocabulary.md`, which records the
+ * `n` behind each group.
+ */
+export type FeatureGroup = 
+/** How worn / how packaged. Independent of `authenticity`. */
+"condition"
+/** Who made it. Mirrors `ProductDocument.authenticity`; see the note there. */
+ | "authenticity"
+/** Regular / limited / early / random-booster / RLC — a real price multiplier. */
+ | "release"
+/** Beyblade battle type: attack · defense · stamina · balance. */
+ | "type"
+/** right-spin · left-spin · dual-spin. */
+ | "spin"
+/** Merchandising state: clearance, on-sale, best-seller. */
+ | "commercial"
+/** Where it came from: japan-import · imported · domestic. */
+ | "sourcing"
+/** Hot Wheels chase variants, incl. the India-only blister card. */
+ | "chase"
+/** PSA/BGS/CGC grade. Pairs with the `sublisting` + `itemCode` axis. */
+ | "grade"
+/** TCG print language. */
+ | "tcg-lang"
+/** TCG product format — booster box vs single differs ~20× in price. */
+ | "tcg-format"
+/** Figure scale, finish and packaging state. */
+ | "figure"
+/** WBO / limited format legality. */
+ | "tournament"
+/**
+ * The CHARACTER the item is of, or belongs to.
+ *
+ * ONE axis across every vertical here, which is the point: a bey's anime
+ * blader (Dragoon G -> Tyson Granger), a comic figure's hero (a Marvel
+ * Legends Spider-Man -> Spider-Man), an anime figure's character
+ * (Nendoroid Luffy -> Monkey D. Luffy), a card's franchise face. A
+ * collector who wants "everything Spider-Man" wants the figure, the card
+ * and the die-cast together, and no category tree can give them that —
+ * each of those three lives under a different root.
+ *
+ * 93 bladers ship with B5, GENERATED from the corpus. Figure and card
+ * characters join in B6, as the same group with the same mechanics; only
+ * the slug prefix differs (`blader-` vs `character-`), so a URL says which
+ * kind of name it is.
+ *
+ * 🛑 A FEATURE and never a tree node, for the reason §4.4 gives: a
+ * character crosses every generation. Tyson Granger owns nine beys spanning
+ * Spin Gear, Magnacore, Engine Gear and HMS, so a `category-tyson-granger`
+ * node would either duplicate all nine under a second parent or break the
+ * one-chain-per-product invariant that lets a category page match on its
+ * own id alone.
+ *
+ * As a feature it is clickable from any listing surface
+ * (`?features=feature-blader-tyson-granger`), it faceted-filters, it is
+ * indexed into `searchTxt` so "Tyson" finds Dragoon, and it composes with
+ * the generation tree rather than competing with it — browse Beyblade
+ * Original, then narrow to Tyson's.
+ */
+ | "character";
+export declare const FEATURE_GROUP_VALUES: readonly ["condition", "authenticity", "release", "type", "spin", "commercial", "sourcing", "chase", "grade", "tcg-lang", "tcg-format", "figure", "tournament", "character"];
+/**
+ * Human-facing section headings for the filter drawer, one per group.
+ *
+ * A `Record<FeatureGroup, string>` on purpose: a fourteenth group cannot
+ * compile without a label, which is the failure mode Root Cause #61 describes
+ * (ten hand-written enumerations of one union, nine of which drifted).
+ */
+export declare const FEATURE_GROUP_LABEL: Record<FeatureGroup, string>;
 export interface ProductFeatureDocument {
     id: string;
     slug: string;
@@ -37,17 +136,48 @@ export interface ProductFeatureDocument {
     /** CSS variable token key, e.g. "--appkit-color-primary". Optional — defaults to neutral. */
     iconColor?: string;
     category: ProductFeatureCategory;
+    /**
+     * The vocabulary namespace — see `FeatureGroup`. Optional only so the 10
+     * pre-B3 rows keep parsing; the seed sets it on every row and the admin form
+     * requires it. An ungrouped feature renders in no facet section.
+     */
+    group?: FeatureGroup;
     scope: ProductFeatureScope;
     productTypes: ProductFeatureProductType[];
     /** Required when scope === "store". */
     storeId?: string;
     isActive: boolean;
     displayOrder: number;
+    /**
+     * Alternative spellings that should FIND this feature.
+     *
+     * Three sources, all measured — see
+     * `docs/research/competitor-crawl-2026-10/counterfeit-signals.md`:
+     *   · part-code pairs, so "rubber flat" finds `RF` and `RF` finds "rubber flat"
+     *   · JP / romaji names
+     *   · 🛑 the counterfeit seller's systematic MISSPELLINGS (`Pegasis`,
+     *     `Jupitar`, `Fireblase`). A counterfeiter's trademark-evasion spelling
+     *     is exactly what a real buyer mistypes, so indexing them makes our
+     *     search tolerant of real typos at zero query-time cost.
+     *
+     * 🛑 Budgeted, not unbounded: these fold into `searchTxt`, which truncates at
+     * 600 tokens SILENTLY, so an over-long alias list evicts tokens nobody chose
+     * to drop.
+     */
+    aliases?: string[];
+    /**
+     * Edge-n-gram search index for this collection, so the picker can search at
+     * all. 🛑 Must be built from the LABEL and `aliases`, never from the slug:
+     * `feature-nib` tokenises to `feature`/`nib`, so the label "New in Box" is
+     * unfindable, which is the same defect `buildProductSearchTxt` has today for
+     * `features[]` (it indexes the raw ids).
+     */
+    searchTxt?: string[];
     createdAt: Date;
     updatedAt: Date;
 }
 export type ProductFeatureCreateInput = Omit<ProductFeatureDocument, "id" | "slug" | "createdAt" | "updatedAt">;
-export type ProductFeatureUpdateInput = Partial<Pick<ProductFeatureDocument, "label" | "description" | "icon" | "iconColor" | "category" | "productTypes" | "isActive" | "displayOrder">>;
+export type ProductFeatureUpdateInput = Partial<Pick<ProductFeatureDocument, "label" | "description" | "icon" | "iconColor" | "category" | "group" | "aliases" | "productTypes" | "isActive" | "displayOrder">>;
 export declare const PRODUCT_FEATURE_SIEVE_FIELDS: {
     readonly label: {
         readonly canFilter: true;
@@ -69,6 +199,14 @@ export declare const PRODUCT_FEATURE_SIEVE_FIELDS: {
         readonly canFilter: true;
         readonly canSort: false;
     };
+    readonly group: {
+        readonly canFilter: true;
+        readonly canSort: false;
+    };
+    readonly searchTxt: {
+        readonly canFilter: true;
+        readonly canSort: false;
+    };
     readonly isActive: {
         readonly canFilter: true;
         readonly canSort: false;

package/dist/features/products/schemas/product-features.js

@@ -17,16 +17,77 @@
 export const PRODUCT_FEATURES_COLLECTION = "productFeatures";
 export const PRODUCT_FEATURE_PREFIX = "feature-";
 export const MAX_STORE_CUSTOM_FEATURES = 20;
-export const MAX_FEATURES_PER_PRODUCT = 10;
+/**
+ * Hard cap on `product.features[].length`.
+ *
+ * 🛑 RAISED 10 → 24 (B3). Ten was sized for *badges* — a handful of
+ * "Free Shipping"-style trust marks. This collection is now the platform's one
+ * controlled VOCABULARY (`tags` is retired), and a single realistic listing
+ * spends six before anything optional: a reproduction, new-in-box,
+ * japan-import, attack-type, right-spin, limited-release bey. A TCG single
+ * adds language + format + grade on top.
+ *
+ * 24 rather than unbounded because `features[]` is `array-contains`-indexed and
+ * feeds `buildProductSearchTxt`, which truncates at 600 tokens SILENTLY — an
+ * unbounded feature list would quietly evict real title/description tokens
+ * from the search index.
+ */
+export const MAX_FEATURES_PER_PRODUCT = 24;
 export function isFeatureIconPath(icon) {
     return icon.trimStart().startsWith("M ") || icon.trimStart().startsWith("m ");
 }
+export const FEATURE_GROUP_VALUES = [
+    "condition",
+    "authenticity",
+    "release",
+    "type",
+    "spin",
+    "commercial",
+    "sourcing",
+    "chase",
+    "grade",
+    "tcg-lang",
+    "tcg-format",
+    "figure",
+    "tournament",
+    "character",
+];
+/**
+ * Human-facing section headings for the filter drawer, one per group.
+ *
+ * A `Record<FeatureGroup, string>` on purpose: a fourteenth group cannot
+ * compile without a label, which is the failure mode Root Cause #61 describes
+ * (ten hand-written enumerations of one union, nine of which drifted).
+ */
+export const FEATURE_GROUP_LABEL = {
+    condition: "Condition",
+    authenticity: "Authenticity",
+    release: "Release type",
+    type: "Battle type",
+    spin: "Spin direction",
+    commercial: "Offers",
+    sourcing: "Sourcing",
+    chase: "Chase & rarity",
+    grade: "Grading",
+    "tcg-lang": "Card language",
+    "tcg-format": "Card format",
+    figure: "Figure details",
+    tournament: "Tournament legality",
+    character: "Blader & character",
+};
 export const PRODUCT_FEATURE_SIEVE_FIELDS = {
     label: { canFilter: true, canSort: true },
     slug: { canFilter: true, canSort: false },
     scope: { canFilter: true, canSort: false },
     storeId: { canFilter: true, canSort: false },
     category: { canFilter: true, canSort: false },
+    group: { canFilter: true, canSort: false },
+    /*
+     * The picker's search. `array-contains` on an edge-n-gram index, the same
+     * shape every other searchable collection uses — a flat Checkbox grid is
+     * fine for 10 rows and unusable at ~60.
+     */
+    searchTxt: { canFilter: true, canSort: false },
     isActive: { canFilter: true, canSort: false },
     displayOrder: { canFilter: false, canSort: true },
     createdAt: { canFilter: false, canSort: true },

package/dist/features/products/schemas/product-features.validators.js

@@ -6,7 +6,7 @@
  * of hand-rolling parallel schemas.
  */
 import { z } from "zod";
-import { annotate } from "../../shell/field-ui-meta";
+import { annotate } from "../../shell/field-ui-meta.js";
 export const PRODUCT_FEATURE_PRODUCT_TYPE_ENUM = z.enum([
     "product",
     "auction",

package/dist/features/products/server.js

@@ -3,7 +3,7 @@
  *
  * Server-only entry point — repositories and API route handlers.
  */
-export * from "./actions";
-export { ProductRepository, productRepository, } from "./repository/products.repository";
-export { GET, POST } from "./api/route";
-export { GET as productItemGET, PATCH as productItemPATCH, DELETE as productItemDELETE, } from "./api/[id]/route";
+export * from "./actions/index.js";
+export { ProductRepository, productRepository, } from "./repository/products.repository.js";
+export { GET, POST } from "./api/route.js";
+export { GET as productItemGET, PATCH as productItemPATCH, DELETE as productItemDELETE, } from "./api/[id]/route.js";

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

@@ -1,4 +1,4 @@
-import { isListingType } from "./listing-type";
+import { isListingType } from "./listing-type.js";
 /**
  * Listing-kind → Badge variant map.
  *

package/dist/features/products/utils/listing-type.js

@@ -1,4 +1,4 @@
-import { ALL_LISTING_TYPES } from "../../../_internal/shared/listing-types/feature-flags";
+import { ALL_LISTING_TYPES } from "../../../_internal/shared/listing-types/feature-flags.js";
 const LISTING_TYPE_SET = new Set(ALL_LISTING_TYPES);
 /** True when `value` is a member of the canonical `ListingType` union. */
 export function isListingType(value) {

package/dist/features/promotions/actions/coupon-actions.js

@@ -4,8 +4,8 @@
  * Pure business functions — auth, rate-limiting, and Next.js specifics
  * are handled by the calling server action in the consumer.
  */
-import { couponsRepository } from "../repository/coupons.repository";
-import { productRepository } from "../../products/repository/products.repository";
+import { couponsRepository } from "../repository/coupons.repository.js";
+import { productRepository } from "../../products/repository/products.repository.js";
 export async function validateCoupon(userId, code, orderTotal) {
     return couponsRepository.validateCoupon(code, userId, orderTotal);
 }

package/dist/features/promotions/actions/index.js

@@ -1,4 +1,4 @@
-export * from "./coupon-actions";
-export * from "./coupon-stacking";
-export * from "./promotions-actions";
-export * from "./seller-coupon-actions";
+export * from "./coupon-actions.js";
+export * from "./coupon-stacking.js";
+export * from "./promotions-actions.js";
+export * from "./seller-coupon-actions.js";

package/dist/features/promotions/actions/promotions-actions.js

@@ -4,9 +4,9 @@
  * Pure business functions — auth, rate-limiting, and Next.js specifics
  * are handled by the calling server action in the consumer.
  */
-import { productRepository } from "../../../features/products/repository/products.repository";
-import { couponsRepository } from "../repository/coupons.repository";
-import { ProductStatusValues } from "../../../features/products/schemas";
+import { productRepository } from "../../../features/products/repository/products.repository.js";
+import { couponsRepository } from "../repository/coupons.repository.js";
+import { ProductStatusValues } from "../../../features/products/schemas/index.js";
 /**
  * Fetch all promotions data in parallel:
  * promoted products, featured products, and active/valid coupons.

package/dist/features/promotions/actions/seller-coupon-actions.js

@@ -4,11 +4,11 @@
  * Business logic for seller-scoped coupon management.
  * Auth, rate-limiting, and input validation are handled by the calling server action.
  */
-import { serverLogger } from "../../../monitoring";
-import { couponsRepository } from "../repository/coupons.repository";
-import { storeRepository } from "../../stores/repository/store.repository";
-import { buildSellerCouponCode } from "../schemas/firestore";
-import { AuthorizationError, ValidationError, NotFoundError, } from "../../../errors";
+import { serverLogger } from "../../../monitoring/index.js";
+import { couponsRepository } from "../repository/coupons.repository.js";
+import { storeRepository } from "../../stores/repository/store.repository.js";
+import { buildSellerCouponCode } from "../schemas/firestore.js";
+import { AuthorizationError, ValidationError, NotFoundError, } from "../../../errors/index.js";
 // --- Create ----------------------------------------------------------------
 export async function sellerCreateCoupon(userId, input) {
     const store = await storeRepository.findByOwnerId(userId);

package/dist/features/promotions/api/route.js

@@ -18,8 +18,8 @@
  * Collection: "coupons"
  */
 import { NextResponse } from "next/server.js";
-import { getProviders } from "../../../contracts";
-import { normalizeError } from "../../../errors/normalize";
+import { getProviders } from "../../../contracts/index.js";
+import { normalizeError } from "../../../errors/normalize.js";
 function param(url, key) {
     return url.searchParams.get(key);
 }

package/dist/features/promotions/columns/index.js

@@ -1,4 +1,4 @@
-import { buildColumns, renderBoolean } from "../../../ui/columns";
+import { buildColumns, renderBoolean } from "../../../ui/columns/index.js";
 /**
  * Default admin column definitions for a coupons/promotions table.
  *

package/dist/features/promotions/components/CouponCard.js

@@ -1,11 +1,11 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { normalizeError } from "../../../errors/normalize";
+import { normalizeError } from "../../../errors/normalize.js";
 import { useState } from "react";
 import { Pencil, Trash2, ToggleLeft, ToggleRight } from "lucide-react";
-import { Badge, BaseListingCard, Button, ConfirmDeleteModal, Div, IconButton, Row, Span, Stack, Text } from "../../../ui";
-import { useLongPress } from "../../../react/hooks/useLongPress";
-import { ACCOUNT_ENDPOINTS } from "../../../constants/api-endpoints";
+import { Badge, BaseListingCard, Button, ConfirmDeleteModal, Div, IconButton, Row, Span, Stack, Text } from "../../../ui/index.js";
+import { useLongPress } from "../../../react/hooks/useLongPress.js";
+import { ACCOUNT_ENDPOINTS } from "../../../constants/api-endpoints.js";
 const CLS_TOGGLE_ON = "h-4 w-4 text-success dark:text-success";
 const CLS_DELETE_BTN = "p-[var(--appkit-space-1-5)] text-[var(--appkit-color-text-muted)] hover:bg-error-surface dark:hover:bg-error-surface hover:text-error dark:hover:text-error transition-colors disabled:opacity-50";
 const TYPE_COLORS = {

package/dist/features/promotions/components/CouponHelpDetails.js

@@ -1,7 +1,7 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { Details, Summary, Stack, Text, Ul, Li, Span } from "../../../ui";
-import { COUPON_HELP } from "../constants/coupon-help";
+import { Details, Summary, Stack, Text, Ul, Li, Span } from "../../../ui/index.js";
+import { COUPON_HELP } from "../constants/coupon-help.js";
 function HelpSection({ heading, items }) {
     return (_jsxs(Stack, { gap: "dense", children: [_jsx(Text, { size: "sm", weight: "semibold", children: heading }), _jsx(Ul, { marker: "disc", indent: "md", spacing: "tight", size: "sm", children: items.map((item) => (_jsx(Li, { color: "muted", children: item }, item))) })] }));
 }