@mohasinac/appkit 4.53.0 → 4.53.1

package/dist/features/products/components/ProductsIndexListing.js

@@ -67,7 +67,7 @@ function dedicatedPageFor(types) {
         label: `Full ${plugin.pluralLabel} filters →`,
     };
 }
-export function ProductsIndexListing({ initialData, listingTypes = GENERIC_PRODUCT_LISTING_TYPES, typeTabs = PRODUCT_TYPE_FILTER_TABS, searchPlaceholder = "Search products...", }) {
+export function ProductsIndexListing({ initialData, listingTypes = GENERIC_PRODUCT_LISTING_TYPES, typeTabs = PRODUCT_TYPE_FILTER_TABS, searchPlaceholder = "Search products...", storeId: scopedStoreId, }) {
     const router = useRouter();
     const table = useUrlTable({ defaults: { pageSize: "24", sort: DEFAULT_SORT } });
     const { showToast } = useToast();
@@ -155,7 +155,7 @@ export function ProductsIndexListing({ initialData, listingTypes = GENERIC_PRODU
         maxPrice: table.get(TABLE_KEYS.MAX_PRICE) ? Number(table.get(TABLE_KEYS.MAX_PRICE)) : undefined,
         condition: table.get(TABLE_KEYS.CONDITION) || undefined,
         brand: table.get(TABLE_KEYS.BRAND) || undefined,
-        storeId: table.get(TABLE_KEYS.STORE_ID) || undefined,
+        storeId: scopedStoreId || table.get(TABLE_KEYS.STORE_ID) || undefined,
         freeShipping: table.get(TABLE_KEYS.FREE_SHIPPING) === "true" ? true : undefined,
         // These three are in FILTER_KEYS (so they count toward the filter badge)
         // but were never put on the wire — the drawer sections were inert.
@@ -345,5 +345,5 @@ export function ProductsIndexListing({ initialData, listingTypes = GENERIC_PRODU
                 ] }), totalPages > 1 && (_jsx(StickyToolbar, { offset: "header+pagination", tone: "translucent", border: true, padding: "toolbar", children: _jsx(Row, { justify: "center", children: _jsx(Pagination, { currentPage: page, totalPages: totalPages, onPageChange: (p) => table.setPage(p) }) }) })), _jsx(Div, { padding: "y-lg", children: isLoading ? (_jsx(Grid, { cols: "cards", gap: "md", children: Array.from({ length: 10 }).map((_, i) => (_jsxs(Div, { className: `${__O.hidden} animate-pulse`, border: "subtle", rounded: "xl", children: [_jsx(Div, { className: "aspect-square", surface: "subtle" }), _jsxs(Stack, { className: `${__P.p3}`, gap: "sm", children: [_jsx(Div, { className: "h-3 w-3/4", surface: "subtle", rounded: "default" }), _jsx(Div, { className: "h-3 w-1/2", surface: "subtle", rounded: "default" }), _jsx(Div, { className: "h-4 w-1/3", surface: "subtle", rounded: "default" })] })] }, i))) })) : (_jsx(ProductGrid, { products: products, getProductHref: (p) => pluginFor(p.listingType ?? "standard").detailRoute(p.slug || p.id), view: view === "grid" ? "card" : "list", onWishlistToggle: handleWishlistToggle, wishlistedIds: wishlistedIds, onAddToCart: handleAddToCart, onBuyNow: handleBuyNow, selectionMode: selection.isSelecting, selectedIds: selection.selectedIdSet, onToggleSelect: selection.toggle })) }), _jsx(CompareOverlay, { isOpen: compareIds.length > 0, productIds: compareIds, productType: "product", onClose: () => {
                     setCompareIds([]);
                     selection.clearSelection();
-                }, onRemove: (id) => setCompareIds((ids) => ids.filter((i) => i !== id)) }), _jsx(FilterDrawer, { open: filterOpen, onOpen: openFilters, onClose: () => setFilterOpen(false), onApply: applyFilters, onReset: onFilterClear, activeCount: filterActiveCount, hideTrigger: true, children: _jsx(ProductFilters, { table: pendingTable, currencyPrefix: "\u20B9", listingTypeOptions: listingTypeOptions, listingTypeFooter: dedicatedPage ? (_jsx(Div, { padding: "x-md", paddingY: "b-sm", children: _jsx(TextLink, { href: dedicatedPage.href, size: "sm", weight: "medium", children: dedicatedPage.label }) })) : null, categoryOptions: categoryOptions, brandOptions: brandOptions, featureOptions: featureOptions }) }), _jsx(LoginRequiredModal, { isOpen: modalOpen, onClose: closeModal, message: modalMessage })] }));
+                }, onRemove: (id) => setCompareIds((ids) => ids.filter((i) => i !== id)), onAdd: (id) => setCompareIds((ids) => (ids.includes(id) ? ids : [...ids, id])) }), _jsx(FilterDrawer, { open: filterOpen, onOpen: openFilters, onClose: () => setFilterOpen(false), onApply: applyFilters, onReset: onFilterClear, activeCount: filterActiveCount, hideTrigger: true, children: _jsx(ProductFilters, { table: pendingTable, currencyPrefix: "\u20B9", listingTypeOptions: listingTypeOptions, listingTypeFooter: dedicatedPage ? (_jsx(Div, { padding: "x-md", paddingY: "b-sm", children: _jsx(TextLink, { href: dedicatedPage.href, size: "sm", weight: "medium", children: dedicatedPage.label }) })) : null, categoryOptions: categoryOptions, brandOptions: brandOptions, featureOptions: featureOptions }) }), _jsx(LoginRequiredModal, { isOpen: modalOpen, onClose: closeModal, message: modalMessage })] }));
 }

package/dist/features/products/components/ShowGroupSection.js

@@ -5,6 +5,8 @@ import Link from "next/link.js";
 import { Div, PricesOnly, Row, Span, Text, Modal, SideDrawer, Button } from "../../../ui/index.js";
 import { MediaImage } from "../../media/MediaImage.js";
 import { GroupMemberPicker } from "./GroupMemberPicker.js";
+import { resolveGroupMemberImage } from "../utils/group-member-image.js";
+import { readGroupRules } from "../../../_internal/shared/features/products/group-rules.js";
 import { formatCurrency } from "../../../utils/number.formatter.js";
 import { normalizeListingType } from "../utils/listing-type.js";
 import { pluginFor } from "../../../_internal/shared/listing-types/_registry.js";
@@ -18,7 +20,7 @@ function memberHref(m) {
     return pluginFor(normalizeListingType(m)).detailRoute(slug);
 }
 function MemberThumb({ member, isCurrent }) {
-    const image = member.images?.[0] ?? "";
+    const image = resolveGroupMemberImage(member);
     const href = memberHref(member);
     const price = formatCurrency(member.price, member.currency ?? "INR");
     return (_jsxs(Link, { href: href, "aria-label": member.title, className: "flex flex-col items-center gap-[var(--appkit-space-1-5)] flex-shrink-0 w-16 group", children: [_jsxs(Div, { rounded: "full", className: `relative w-14 h-14 overflow-hidden border-2 transition-all ${isCurrent
@@ -48,7 +50,18 @@ export function ShowGroupSection({ groupId, currentSlug, isParent, groupTitle })
     // The overlay is now a PICKER, not a read-only table: pick how many of each
     // member you want and add the whole selection as one cart line. The picker
     // stands itself down (read-only, no CTA) when the group spans sellers.
-    const tableContent = (_jsx(GroupMemberPicker, { groupId: groupId, groupSource: "product-group", members: members, onAdded: () => setShowAll(false), onAuthRequired: () => setShowAll(false) }));
+    const tableContent = (_jsx(GroupMemberPicker, { groupId: groupId, groupSource: "product-group", members: members, 
+        /*
+         * A product group's rules live on the PARENT, and the parent is one of
+         * the members this component already fetched — found by `isGroupParent`
+         * rather than by position, because the endpoint makes no ordering
+         * promise and the parent is not reliably first.
+         *
+         * 🛑 This is why the five rule fields are in `PRODUCT_PUBLIC_FIELDS`: they
+         * reach `toPublicGroupMember` through that allow-list, and without it the
+         * picker would silently see no rules and permit what the server refuses.
+         */
+        rules: readGroupRules(members.find((m) => m.isGroupParent)), onAdded: () => setShowAll(false), onAuthRequired: () => setShowAll(false) }));
     return (_jsxs(_Fragment, { children: [_jsxs(Div, { className: `${__O.hidden}`, surface: "muted", rounded: "xl", border: "default", children: [_jsxs(Row, { role: "button", tabIndex: 0, onClick: () => setOpen((v) => !v), onKeyDown: (e) => { if (e.key === "Enter" || e.key === " ") {
                             e.preventDefault();
                             setOpen((v) => !v);

package/dist/features/products/components/SparesListView.d.ts

@@ -0,0 +1,7 @@
+import React from "react";
+type SearchParams = Record<string, string | string[]>;
+export interface SparesListViewProps {
+    searchParams?: SearchParams;
+}
+export declare function SparesListView({ searchParams }: SparesListViewProps): Promise<React.JSX.Element>;
+export {};

package/dist/features/products/components/SparesListView.js

@@ -0,0 +1,39 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Container, Heading, Main, Section, Text, TextLink } from "../../../ui/index.js";
+import { AdSlot } from "../../homepage/components/AdSlot.js";
+import { ProductsIndexListing } from "./ProductsIndexListing.js";
+import { PRODUCT_FIELDS } from "../../../constants/field-names.js";
+import { sortBy } from "../../../constants/sort.js";
+import { ROUTES } from "../../../next/routing/route-map.js";
+import { listPublicProducts, parsePublicProductParams, defaultAvailabilityForListingTypes, } from "../../../_internal/server/features/products/list-public.js";
+const DEFAULT_PAGE_SIZE = 24;
+const DEFAULT_SORT = sortBy(PRODUCT_FIELDS.CREATED_AT);
+/** The one type this page spans. Named so the two call sites cannot disagree. */
+const SPARES_LISTING_TYPES = ["spares"];
+export async function SparesListView({ searchParams = {} }) {
+    /*
+     * Filter semantics live in `listPublicProducts`, shared verbatim with
+     * `/api/products`, so the SSR first paint and the client's refetch cannot
+     * disagree about what the default view means. That matters more here than it
+     * looks: every public listing hook sets `staleTime: Infinity` once given SSR
+     * `initialData`, so a disagreement is FROZEN for that query key and no
+     * refetch ever repairs it (Root Cause #30).
+     */
+    const result = await listPublicProducts(parsePublicProductParams(searchParams, {
+        listingTypes: SPARES_LISTING_TYPES,
+        pageSize: DEFAULT_PAGE_SIZE,
+        sorts: DEFAULT_SORT,
+        // Derived from the plugin's own `hideDefault`, so this page and
+        // `ProductsIndexListing` cannot mirror two different literals.
+        ...defaultAvailabilityForListingTypes(SPARES_LISTING_TYPES),
+    }));
+    return (_jsxs(Main, { children: [_jsx(Section, { border: "bottom-subtle", paddingY: "b-md", padding: "t-xl", children: _jsxs(Container, { size: "xl", children: [_jsx(Heading, { level: 1, size: "3xl", weight: "bold", color: "primary", children: "Spares" }), _jsx(Text, { className: "mt-1", color: "muted", size: "sm", children: "Single components off disassembled tops \u2014 attack rings, weight disks, drivers, bits. Sellers list what they have spare; most are one of a kind." }), _jsxs(Text, { className: "mt-2", size: "sm", children: ["Not sure which part you need?", " ", _jsx(TextLink, { href: String(ROUTES.PUBLIC.PARTS), children: "Browse the parts glossary" }), " ", "\u2014 every component, what it does, and which tops use it."] })] }) }), _jsxs(Container, { size: "xl", padding: "x-md", children: [_jsx(AdSlot, { id: "listing-sidebar-top", className: "mb-4 mt-4" }), _jsx(ProductsIndexListing
+                    // `undefined`, not `null` — React Query treats `null` as defined
+                    // data, so a failed query would freeze an empty grid forever under
+                    // `staleTime: Infinity`. Same reasoning as ProductsIndexPageView.
+                    , { 
+                        // `undefined`, not `null` — React Query treats `null` as defined
+                        // data, so a failed query would freeze an empty grid forever under
+                        // `staleTime: Infinity`. Same reasoning as ProductsIndexPageView.
+                        initialData: result ?? undefined, listingTypes: SPARES_LISTING_TYPES, searchPlaceholder: "Search spares by part, colour or model..." }), _jsx(AdSlot, { id: "listing-sidebar-bottom", className: "mt-8" })] })] }));
+}

package/dist/features/products/constants/action-defs.d.ts

@@ -411,6 +411,7 @@ export declare const SELLER_BULK_ACTIONS: {
     readonly live: readonly ["row-delete"];
     readonly art: readonly ["row-delete"];
     readonly stickers: readonly ["row-delete"];
+    readonly spares: readonly ["row-delete"];
     readonly auctions: readonly ["row-delete"];
     readonly preOrders: readonly ["row-delete"];
     readonly prizeDraws: readonly ["row-delete"];

package/dist/features/products/constants/action-defs.js

@@ -566,6 +566,7 @@ export const SELLER_BULK_ACTIONS = {
     live: [ROW_ACTION_ID.DELETE],
     art: [ROW_ACTION_ID.DELETE],
     stickers: [ROW_ACTION_ID.DELETE],
+    spares: [ROW_ACTION_ID.DELETE],
     auctions: [ROW_ACTION_ID.DELETE],
     preOrders: [ROW_ACTION_ID.DELETE],
     prizeDraws: [ROW_ACTION_ID.DELETE],

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

@@ -267,16 +267,106 @@ export declare class ProductRepository extends BaseRepository<ProductDocument> {
     updateAvailableQuantity(productId: string, quantity: number): Promise<void>;
     updateBid(productId: string, bidAmount: number, bidCount: number): Promise<void>;
     findAvailable(): Promise<ProductDocument[]>;
+    /**
+     * Every member of a group, UNFILTERED — drafts, and every listing type.
+     *
+     * 🛑 This is the scope `dissolveGroup` needs and the ONLY one that may be
+     * unfiltered. A filtered dissolve leaves the excluded members carrying a
+     * `groupId` pointing at a group that no longer exists, which nothing ever
+     * clears — and that orphan is invisible until someone wonders why a product
+     * claims to be in a group with no other members.
+     */
+    findAllByGroupId(groupId: string): Promise<ProductDocument[]>;
+    /**
+     * Group members a BUYER may see: eligible types, published only.
+     *
+     * 🛑 The type filter is DERIVED from `canJoinProductGroup`, not hard-coded.
+     * It used to be a literal `["standard", "pre-order"]`, which silently dropped
+     * every `stickers` / `art` member from the query — so `ShowGroupSection` saw
+     * one member and returned null, and the picker was unreachable with nothing
+     * erroring anywhere (Root Cause #58).
+     *
+     * 🛑 The `status` filter is NEW and is a leak fix, not a tightening. There
+     * was no status filter at all, so DRAFT members were reaching the public
+     * `/api/products/group/[groupId]` payload; widening the type list without
+     * this would have widened that leak at the same time.
+     */
+    findGroupMembersForPublic(groupId: string): Promise<ProductDocument[]>;
+    /**
+     * Union the child-side query with the PARENT's own `groupChildSlugs`.
+     *
+     * Mirrors `resolveBundleMemberIds`, and exists for the same reason: Root
+     * Cause #42 documented a parent carrying `groupChildSlugs` while its children
+     * had no `groupId`, so a child-side query resolved only the parent and the
+     * group rendered as one member. The repository's six mutating methods all
+     * write both sides in one batch, so code cannot produce that state — but a
+     * seeded fixture or a direct Firestore edit still can, and the READER was
+     * never made resilient. `listBundleMembers` got this fix; this did not.
+     */
+    private withParentSideFallback;
+    /**
+     * @deprecated Ambiguous about scope — say which one you mean.
+     * Kept so no caller silently changes behaviour; it resolves to the PUBLIC
+     * scope, which is what every existing caller wanted.
+     */
     findByGroupId(groupId: string): Promise<ProductDocument[]>;
     startGroup(productId: string, slug: string): Promise<void>;
     updateGroupTitle(productId: string, groupTitle: string): Promise<void>;
     dissolveGroup(groupId: string): Promise<void>;
+    /**
+     * Link ONE child into a parent's group.
+     *
+     * 🛑 `arrayUnion`, not a spread of the in-memory `parent.groupChildSlugs`.
+     *
+     * The spread read a snapshot the CALLER was holding, so linking N children in
+     * a loop produced exactly ONE entry: every iteration computed
+     * `[...(stale ?? []), child]` from the same pre-loop document and the last
+     * write won. Nothing errored — each child got its own `groupId` correctly, so
+     * `findAllByGroupId` found them all while the parent's own
+     * `groupChildSlugs` claimed one member, which is what the group picker's
+     * fallback path and `GroupSettingsPanel` read.
+     *
+     * `arrayUnion` is also idempotent, so re-linking an existing child is a
+     * no-op instead of a duplicate id.
+     *
+     * For a known set, prefer `linkChildrenToGroup` below — one batch instead of
+     * N, which matters against Rule #6's round-trip budget when promoting a
+     * 60-part sticker sheet.
+     */
     linkChildToGroup(parent: ProductDocument, child: ProductDocument): Promise<void>;
+    /**
+     * Link SEVERAL children into a parent's group in one batch.
+     *
+     * Built for `promoteStickerSheetToListings`, which links every unique part of
+     * a sheet at once — N calls to `linkChildToGroup` would be N batch commits
+     * for work that is one logical change.
+     */
+    linkChildrenToGroup(parent: ProductDocument, children: readonly ProductDocument[]): Promise<void>;
     unlinkChildFromGroup(parent: ProductDocument, child: ProductDocument): Promise<void>;
     leaveGroup(child: ProductDocument, parent: ProductDocument | null): Promise<void>;
     addChildProduct(parent: ProductDocument, child: Omit<import("../schemas/firestore").ProductCreateInput, "groupId" | "isGroupParent" | "groupParentSlug" | "groupTitle">): Promise<ProductDocument>;
     deleteByStore(storeId: string): Promise<number>;
     delete(id: string): Promise<void>;
+    /**
+     * Every live listing OF one glossary part, across all stores.
+     *
+     * 🛑 NOT filtered by `listingType`, deliberately. Both `spares` and the
+     * 972 generated per-leaf catalogue rows (which are `standard`) carry
+     * `partGlossaryId`, and a buyer on `/parts/{slot}/{code}` wants any listing
+     * of that part — not only the ones that happen to be filed under the newer
+     * type. Narrowing to `spares` would hide most of the real inventory.
+     *
+     * 🛑 `orderBy` is `createdAt`, which EVERY document carries
+     * (`BaseRepository.create` writes it). Ordering by an optional field silently
+     * excludes every row lacking it — Root Cause #100, where `itemsSold` on zero
+     * of 95 products made a store`s whole review endpoint return nothing.
+     *
+     * Availability is filtered IN MEMORY rather than in the query: "available" is
+     * negation-shaped and no query expresses it, which is the asymmetry
+     * `baseAvailable` exists for. The window is bounded, so the cost is a few
+     * rows read and discarded.
+     */
+    findByPartGlossaryId(partGlossaryId: string, limit?: number): Promise<ProductDocument[]>;
     static readonly SIEVE_FIELDS: {
         id: {
             canFilter: boolean;
@@ -330,6 +420,14 @@ export declare class ProductRepository extends BaseRepository<ProductDocument> {
             canFilter: boolean;
             canSort: boolean;
         };
+        partGlossaryId: {
+            canFilter: boolean;
+            canSort: boolean;
+        };
+        colourway: {
+            canFilter: boolean;
+            canSort: boolean;
+        };
         isPromoted: {
             canFilter: boolean;
             canSort: boolean;

package/dist/features/products/repository/products.repository.js

@@ -1,5 +1,5 @@
 import { normalizeError } from "../../../errors/normalize.js";
-import { increment, serverTimestamp } from "../../../contracts/field-ops.js";
+import { arrayUnion, increment, serverTimestamp } from "../../../contracts/field-ops.js";
 // 🛑 `../../../errors` re-exports the REAL ValidationError (errors/validation-error),
 // which is the one `mapToHttpError` instanceof-checks to produce a 400. The
 // unrelated same-named class under `_internal/shared/errors` falls through every
@@ -24,7 +24,7 @@ import { planSearchTxt, beginSearchWindow, emptySearchResult, } from "../../../u
 // One definition of "which fields feed searchTxt", shared with the seed
 // wrapper. Three copies existed and two were missing the same three fields.
 import { buildProductSearchTxt } from "../../../utils/search-txt-builders.js";
-import { PRODUCT_COLLECTION, ProductStatusValues } from "../schemas/index.js";
+import { PRODUCT_COLLECTION, ProductStatusValues, toProductImages } from "../schemas/index.js";
 // Collection NAMES only — deliberately not `categoriesRepository` or
 // `taxCodesRepository`. See deriveTaxonomy()'s header for why these are raw
 // reads: no repository in this codebase imports another feature's, because of
@@ -45,6 +45,12 @@ import { MAX_FEATURES_PER_PRODUCT } from "../schemas/product-features.js";
 // The ONE `{{placeholder}}` implementation, promoted out of the FAQ schema in
 // B3. A second regex here would be Root Cause #75's shape.
 import { interpolate } from "../../../_internal/shared/templating/placeholders.js";
+/*
+ * From their DEFINING modules, not a barrel — a repository reaching the wide
+ * entry is how the Turbopack client-bundle trap gets re-opened (Root Cause #18).
+ */
+import { ALL_LISTING_TYPES } from "../../../_internal/shared/listing-types/feature-flags.js";
+import { pluginFor } from "../../../_internal/shared/listing-types/_registry.js";
 import { PRODUCT_FIELDS } from "../../../constants/field-names.js";
 /**
  * Canonical listing-kind tokens used in `listingType`. Note: the public Sieve
@@ -73,6 +79,21 @@ const LISTING_KIND_ALIAS_MAP = {
     live: LISTING_TYPE_VALUES.LIVE,
     art: LISTING_TYPE_VALUES.ART,
     stickers: LISTING_TYPE_VALUES.STICKERS,
+    /*
+     * 🛑 Root Cause #58 lives here, and it is the single most expensive line to
+     * omit in this whole change. The alias returns `""` for an unrecognised
+     * token and `expandFilterAliases` then DROPS the empty clause — so a missing
+     * entry does not error, it deletes the `listingType` filter from the query.
+     * `art` and `stickers` were added to the union, the registry and the
+     * capability map and not to this map, and every art/sticker browse page
+     * silently returned the entire catalogue until someone reported it.
+     *
+     * `Record<ProductListingKind, string>` makes it compile-checked against THAT
+     * union — but `ProductListingKind` is itself hand-written above and is not
+     * checked against `ListingType`, which is why this is still on the unchecked
+     * list.
+     */
+    spares: LISTING_TYPE_VALUES.SPARES,
     // Legacy → canonical.
     product: LISTING_TYPE_VALUES.STANDARD,
     preorder: LISTING_TYPE_VALUES.PRE_ORDER,
@@ -232,6 +253,17 @@ export class ProductRepository extends BaseRepository {
         if (!doc.categorySlugs || doc.categorySlugs.length === 0) {
             doc.categorySlugs = doc.category ? [doc.category] : [];
         }
+        /*
+         * A6 — widen a legacy `images: string[]` document to `ProductImage[]`.
+         *
+         * 🛑 This is HALF the normalisation and must stay paired with the write
+         * half in `create`/`update` below. Read-only widening is Root Cause #101
+         * exactly: the field would be the object form on every object anyone
+         * inspects and still a bare string array in Firestore, so the next write
+         * of an untouched document would persist whichever shape the caller
+         * happened to hold.
+         */
+        doc.images = toProductImages(doc.images);
         return doc;
     }
     /**
@@ -833,6 +865,13 @@ export class ProductRepository extends BaseRepository {
             ...data,
             ...derived,
             ...stock,
+            /*
+             * A6 — only when the write NAMES `images`. An unconditional
+             * `toProductImages(data.images)` would write `[]` over a real gallery on
+             * every stock decrement and status flip, because `data` does not carry
+             * the field at all on those paths.
+             */
+            ...(data.images !== undefined ? { images: toProductImages(data.images) } : {}),
             searchTxt: buildProductSearchTxt(merged),
         });
         this.cacheSet(updated);
@@ -907,7 +946,17 @@ export class ProductRepository extends BaseRepository {
         // all. A seed row already carrying the correct chain derives to the same
         // value, so this is a no-op for every existing fixture.
         const derived = await this.deriveTaxonomy(input, true);
-        const withTaxonomy = { ...input, ...derived };
+        /*
+         * A6 — the WRITE half of the `images` normalisation (the read half is in
+         * `mapDoc`). Every create path funnels through here, so a caller handing
+         * us `string[]` — a seed row, an older client, the shipment-link route —
+         * stores the object form rather than leaving the collection mixed.
+         */
+        const withTaxonomy = {
+            ...input,
+            ...derived,
+            ...(input.images !== undefined ? { images: toProductImages(input.images) } : {}),
+        };
         const productData = {
             ...withTaxonomy,
             barcodeId,
@@ -1053,17 +1102,89 @@ export class ProductRepository extends BaseRepository {
             .get();
         return snapshot.docs.map((doc) => this.mapDoc(doc));
     }
-    async findByGroupId(groupId) {
-        // Tier GP: groups may mix standard products + pre-orders (never auctions).
+    /**
+     * Every member of a group, UNFILTERED — drafts, and every listing type.
+     *
+     * 🛑 This is the scope `dissolveGroup` needs and the ONLY one that may be
+     * unfiltered. A filtered dissolve leaves the excluded members carrying a
+     * `groupId` pointing at a group that no longer exists, which nothing ever
+     * clears — and that orphan is invisible until someone wonders why a product
+     * claims to be in a group with no other members.
+     */
+    async findAllByGroupId(groupId) {
         const snapshot = await this.db
             .collection(this.collection)
             .where("groupId", "==", groupId)
-            .where(PRODUCT_FIELDS.LISTING_TYPE, "in", [
-            LISTING_TYPE_VALUES.STANDARD,
-            LISTING_TYPE_VALUES.PRE_ORDER,
-        ])
             .get();
-        return snapshot.docs.map((doc) => this.mapDoc(doc));
+        const byQuery = snapshot.docs.map((doc) => this.mapDoc(doc));
+        return this.withParentSideFallback(groupId, byQuery);
+    }
+    /**
+     * Group members a BUYER may see: eligible types, published only.
+     *
+     * 🛑 The type filter is DERIVED from `canJoinProductGroup`, not hard-coded.
+     * It used to be a literal `["standard", "pre-order"]`, which silently dropped
+     * every `stickers` / `art` member from the query — so `ShowGroupSection` saw
+     * one member and returned null, and the picker was unreachable with nothing
+     * erroring anywhere (Root Cause #58).
+     *
+     * 🛑 The `status` filter is NEW and is a leak fix, not a tightening. There
+     * was no status filter at all, so DRAFT members were reaching the public
+     * `/api/products/group/[groupId]` payload; widening the type list without
+     * this would have widened that leak at the same time.
+     */
+    async findGroupMembersForPublic(groupId) {
+        const eligible = ALL_LISTING_TYPES.filter((t) => pluginFor(t).canJoinProductGroup);
+        const snapshot = await this.db
+            .collection(this.collection)
+            .where("groupId", "==", groupId)
+            // `in` caps at 30 values; this is 4 of 9 today and cannot approach it.
+            .where(PRODUCT_FIELDS.LISTING_TYPE, "in", eligible)
+            .where(PRODUCT_FIELDS.STATUS, "==", ProductStatusValues.PUBLISHED)
+            .get();
+        const byQuery = snapshot.docs.map((doc) => this.mapDoc(doc));
+        const withFallback = await this.withParentSideFallback(groupId, byQuery);
+        /*
+         * 🛑 The fallback results are filtered TOO. Without this the fallback
+         * becomes the hole the query just closed — a draft or an ineligible member
+         * would reach the public payload through the parent's own list.
+         */
+        const eligibleSet = new Set(eligible);
+        return withFallback.filter((p) => eligibleSet.has(String(p.listingType ?? LISTING_TYPE_VALUES.STANDARD)) &&
+            p.status === ProductStatusValues.PUBLISHED);
+    }
+    /**
+     * Union the child-side query with the PARENT's own `groupChildSlugs`.
+     *
+     * Mirrors `resolveBundleMemberIds`, and exists for the same reason: Root
+     * Cause #42 documented a parent carrying `groupChildSlugs` while its children
+     * had no `groupId`, so a child-side query resolved only the parent and the
+     * group rendered as one member. The repository's six mutating methods all
+     * write both sides in one batch, so code cannot produce that state — but a
+     * seeded fixture or a direct Firestore edit still can, and the READER was
+     * never made resilient. `listBundleMembers` got this fix; this did not.
+     */
+    async withParentSideFallback(groupId, byQuery) {
+        const seen = new Set(byQuery.map((p) => p.id));
+        /*
+         * `startGroup` sets `groupId = parent.slug`, so the group id IS the
+         * parent's slug and one lookup finds it. If that ever stops being true the
+         * fallback simply finds nothing, which is the same behaviour as today.
+         */
+        const parent = byQuery.find((p) => p.isGroupParent) ?? (await this.findById(groupId));
+        const missing = (parent?.groupChildSlugs ?? []).filter((id) => !seen.has(id));
+        if (missing.length === 0)
+            return byQuery;
+        const extra = await Promise.all(missing.map((id) => this.findById(id)));
+        return [...byQuery, ...extra.filter((p) => p !== null)];
+    }
+    /**
+     * @deprecated Ambiguous about scope — say which one you mean.
+     * Kept so no caller silently changes behaviour; it resolves to the PUBLIC
+     * scope, which is what every existing caller wanted.
+     */
+    async findByGroupId(groupId) {
+        return this.findGroupMembersForPublic(groupId);
     }
     async startGroup(productId, slug) {
         await this.getCollection().doc(productId).update({
@@ -1076,7 +1197,10 @@ export class ProductRepository extends BaseRepository {
         await this.getCollection().doc(productId).update({ groupTitle });
     }
     async dissolveGroup(groupId) {
-        const members = await this.findByGroupId(groupId);
+        // UNFILTERED on purpose — see findAllByGroupId. Dissolving must clear every
+        // member's fields, including drafts and ineligible types, or they keep a
+        // groupId pointing at nothing.
+        const members = await this.findAllByGroupId(groupId);
         const batch = this.db.batch();
         const clearFields = {
             groupId: null,
@@ -1090,15 +1214,62 @@ export class ProductRepository extends BaseRepository {
         }
         await batch.commit();
     }
+    /**
+     * Link ONE child into a parent's group.
+     *
+     * 🛑 `arrayUnion`, not a spread of the in-memory `parent.groupChildSlugs`.
+     *
+     * The spread read a snapshot the CALLER was holding, so linking N children in
+     * a loop produced exactly ONE entry: every iteration computed
+     * `[...(stale ?? []), child]` from the same pre-loop document and the last
+     * write won. Nothing errored — each child got its own `groupId` correctly, so
+     * `findAllByGroupId` found them all while the parent's own
+     * `groupChildSlugs` claimed one member, which is what the group picker's
+     * fallback path and `GroupSettingsPanel` read.
+     *
+     * `arrayUnion` is also idempotent, so re-linking an existing child is a
+     * no-op instead of a duplicate id.
+     *
+     * For a known set, prefer `linkChildrenToGroup` below — one batch instead of
+     * N, which matters against Rule #6's round-trip budget when promoting a
+     * 60-part sticker sheet.
+     */
     async linkChildToGroup(parent, child) {
+        await this.linkChildrenToGroup(parent, [child]);
+    }
+    /**
+     * Link SEVERAL children into a parent's group in one batch.
+     *
+     * Built for `promoteStickerSheetToListings`, which links every unique part of
+     * a sheet at once — N calls to `linkChildToGroup` would be N batch commits
+     * for work that is one logical change.
+     */
+    async linkChildrenToGroup(parent, children) {
+        if (children.length === 0)
+            return;
         const batch = this.db.batch();
-        batch.update(this.getCollection().doc(child.id), {
-            groupId: parent.groupId,
-            groupParentSlug: parent.slug ?? parent.id,
-            groupTitle: parent.groupTitle ?? null,
-        });
+        for (const child of children) {
+            batch.update(this.getCollection().doc(child.id), {
+                groupId: parent.groupId,
+                groupParentSlug: parent.slug ?? parent.id,
+                groupTitle: parent.groupTitle ?? null,
+            });
+        }
         batch.update(this.getCollection().doc(parent.id), {
-            groupChildSlugs: [...(parent.groupChildSlugs ?? []), child.id],
+            /*
+             * Ids, matching `unlinkChildFromGroup`'s filter, which removes by id OR
+             * slug. These are pure slugs for products (`id === slug`), so the two
+             * agree — but the field name says "slugs" and the stored values are ids,
+             * which is worth knowing before writing a reader that assumes either.
+             */
+            /*
+             * 🛑 `arrayUnion` from the CONTRACTS layer, not `firebase-admin`
+             * directly. Two sibling repositories import `FieldValue` from
+             * firebase-admin and this one deliberately does not — its own imports go
+             * through `contracts/field-ops`, which is what keeps the admin SDK out of
+             * this module's static import graph (Root Cause #24/#6).
+             */
+            groupChildSlugs: arrayUnion(...children.map((c) => c.id)),
         });
         await batch.commit();
     }
@@ -1185,6 +1356,39 @@ export class ProductRepository extends BaseRepository {
         await super.delete(id);
         await this.syncCategoryCounts(prior, null);
     }
+    /**
+     * Every live listing OF one glossary part, across all stores.
+     *
+     * 🛑 NOT filtered by `listingType`, deliberately. Both `spares` and the
+     * 972 generated per-leaf catalogue rows (which are `standard`) carry
+     * `partGlossaryId`, and a buyer on `/parts/{slot}/{code}` wants any listing
+     * of that part — not only the ones that happen to be filed under the newer
+     * type. Narrowing to `spares` would hide most of the real inventory.
+     *
+     * 🛑 `orderBy` is `createdAt`, which EVERY document carries
+     * (`BaseRepository.create` writes it). Ordering by an optional field silently
+     * excludes every row lacking it — Root Cause #100, where `itemsSold` on zero
+     * of 95 products made a store`s whole review endpoint return nothing.
+     *
+     * Availability is filtered IN MEMORY rather than in the query: "available" is
+     * negation-shaped and no query expresses it, which is the asymmetry
+     * `baseAvailable` exists for. The window is bounded, so the cost is a few
+     * rows read and discarded.
+     */
+    async findByPartGlossaryId(partGlossaryId, limit = 12) {
+        if (!partGlossaryId)
+            return [];
+        const snap = await this.getCollection()
+            .where(PRODUCT_FIELDS.PART_GLOSSARY_ID, "==", partGlossaryId)
+            .where(PRODUCT_FIELDS.STATUS, "==", PRODUCT_FIELDS.STATUS_VALUES.PUBLISHED)
+            .orderBy(PRODUCT_FIELDS.CREATED_AT, "desc")
+            // Over-fetch, because the availability filter below removes rows. Taking
+            // exactly `limit` here would return fewer than `limit` buyable listings
+            // whenever any of them were sold.
+            .limit(Math.min(60, limit * 3))
+            .get();
+        return snap.docs.map((d) => this.mapDoc(d)).slice(0, limit);
+    }
     /**
      * Shared scope construction for `list()` and `countBy*()` — both must narrow
      * by exactly the same store/status/category/search predicates or a tab's
@@ -1481,6 +1685,20 @@ ProductRepository.SIEVE_FIELDS = {
     // admin and seller product lists.
     featured: { canFilter: true, canSort: true },
     listingType: { canFilter: true, canSort: false },
+    /*
+     * 🛑 Filterable so a `partGlossaryId` filter is not SILENTLY DROPPED.
+     * `sieve.ts` sets `throwExceptions: false`, so a field absent from this map
+     * does not raise — `findField` returns undefined and the clause vanishes,
+     * which on a page scoped to one part means the ENTIRE catalogue comes back
+     * (Root Cause #62). Both of these are real `ProductDocument` fields, so
+     * neither is the orphan half of that pattern.
+     *
+     * `canSort: false` on both: they are identity, not an ordering anyone wants
+     * — and a sort option whose field is `canSort: false` is dropped just as
+     * silently (Root Cause #63).
+     */
+    partGlossaryId: { canFilter: true, canSort: false },
+    colourway: { canFilter: true, canSort: false },
     isPromoted: { canFilter: true, canSort: true },
     isOnSale: { canFilter: true, canSort: false },
     price: { canFilter: true, canSort: true },