@mohasinac/appkit 4.42.18 → 4.44.0

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

@@ -47,6 +47,97 @@ export const bundleQueryRuleSchema = z.discriminatedUnion("type", [
         limit: z.number().int().positive(),
     }),
 ]);
+/*
+ * ── Category-owned content (B3), mirrored here in B5 ────────────────────────
+ *
+ * 🛑 These three were added to `CategoryDocument` in B3 and NOT to this
+ * schema, which is the drift this file has a history of: `highlights` and
+ * `faqs` sat in the interface with no mirror for months, and nothing enforces
+ * parity between the two. Mirroring them is what lets the admin category
+ * editor (C2) validate a template body server-side instead of trusting the
+ * form.
+ */
+export const categoryDescriptionTemplateSchema = z.object({
+    id: z.string(),
+    label: z.string(),
+    variant: z.enum(["default", "new_in_box", "new_in_packet", "pre_owned", "replica"]),
+    body: z.string(),
+    /** Absent means "re-parse", never "no slots" — see the field's own doc. */
+    placeholders: z.array(z.string()).optional(),
+    isTested: z.boolean().optional(),
+    version: z.number().int().optional(),
+});
+export const categorySpecificationSchema = z.object({
+    name: z.string(),
+    value: z.string(),
+    unit: z.string().optional(),
+});
+export const categoryPriceGuidanceSchema = z.object({
+    currency: z.literal("INR"),
+    market: z
+        .object({
+        median: rupeesSchema,
+        // Optional on purpose — see the field docs in category-content.ts. The
+        // crawl measured quartiles for some verticals and a median-plus-range
+        // for others, and a required p25 would force a range to be retyped as a
+        // quartile.
+        p25: rupeesSchema.optional(),
+        p75: rupeesSchema.optional(),
+        sampleSize: z.number().int().positive().optional(),
+        asOf: firestoreDateSchema,
+        soldOutShare: z.number().min(0).max(1).optional(),
+        source: z.string().optional(),
+    })
+        .optional(),
+    /*
+     * 🛑 No `.default()` anywhere in here. An absent `sold` means "we have no
+     * sales yet" and a zeroed one would render as "things sell here for ₹0" —
+     * which is worse than silence, and is exactly what a defaulting schema would
+     * manufacture on the first quiet night.
+     */
+    sold: z
+        .object({
+        min: rupeesSchema,
+        median: rupeesSchema,
+        max: rupeesSchema,
+        sampleSize: z.number().int().positive(),
+        windowDays: z.number().int().positive(),
+        byPath: z
+            .object({
+            standard: z.number().int().nonnegative().optional(),
+            auction: z.number().int().nonnegative().optional(),
+            offer: z.number().int().nonnegative().optional(),
+        })
+            .optional(),
+    })
+        .optional(),
+    lastSold: z
+        .object({
+        amount: rupeesSchema,
+        at: firestoreDateSchema,
+        via: z.enum(["standard", "auction", "offer"]).optional(),
+    })
+        .optional(),
+});
+export const categoryProductDefaultsSchema = z.object({
+    taxCodeId: z.string().optional(),
+    specifications: z.array(categorySpecificationSchema).optional(),
+    defaultFeatures: z.array(z.string()).optional(),
+    defaultCondition: z.string().optional(),
+    defaultAuthenticity: z.enum(["original", "reproduction", "unverified"]).optional(),
+    inTheBox: z.array(z.string()).optional(),
+    priceGuidance: categoryPriceGuidanceSchema.optional(),
+    seoTitleTemplate: z.string().optional(),
+    seoDescriptionTemplate: z.string().optional(),
+    seoKeywords: z.array(z.string()).optional(),
+    weightG: z.number().nonnegative().optional(),
+    dimensionsCm: z
+        .object({ l: z.number().positive(), w: z.number().positive(), h: z.number().positive() })
+        .optional(),
+    shippingPaidBy: z.string().optional(),
+    fragile: z.boolean().optional(),
+    faqTemplates: z.array(z.object({ question: z.string(), answer: z.string() })).optional(),
+});
 export const bundleItemDetailSchema = z.object({
     productId: z.string(),
     drawCount: z.number().int().nonnegative().optional(),
@@ -78,6 +169,11 @@ export const categoryFirestoreSchema = z.object({
     brandFounded: z.number().int().optional(),
     highlights: z.array(z.string()).optional(),
     faqs: z.array(z.object({ question: z.string(), answer: z.string() })).optional(),
+    aliases: z.array(z.string()).optional(),
+    contentBody: z.string().optional(),
+    descriptionTemplates: z.array(categoryDescriptionTemplateSchema).optional(),
+    productDefaults: categoryProductDefaultsSchema.optional(),
+    searchTxt: z.array(z.string()).optional(),
     bundleKind: z.enum(["special", "brand"]).optional(),
     brandSlug: z.string().optional(),
     bundlePrice: rupeesSchema.optional(),

package/dist/features/categories/server.d.ts

@@ -7,3 +7,4 @@ export * from "./actions";
 export { CategoriesRepository, categoriesRepository, } from "./repository/categories.repository";
 export { GET as categoriesGET, GET, POST } from "./api/route";
 export { categoryItemGET, categoryItemPATCH, categoryItemDELETE, } from "./api/[id]/route";
+export { GET as categoryDescriptionTemplateGET } from "./api/[id]/description-template/route";

package/dist/features/categories/server.js

@@ -7,3 +7,10 @@ export * from "./actions";
 export { CategoriesRepository, categoriesRepository, } from "./repository/categories.repository";
 export { GET as categoriesGET, GET, POST } from "./api/route";
 export { categoryItemGET, categoryItemPATCH, categoryItemDELETE, } from "./api/[id]/route";
+/*
+ * The seller form's template read. A separate route rather than a field on
+ * `categoryItemGET` because that one returns the whole document and is not
+ * edge-cached — this is a narrow, hour-cacheable answer to one question, hit
+ * on every category change in the form.
+ */
+export { GET as categoryDescriptionTemplateGET } from "./api/[id]/description-template/route";

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

@@ -57,6 +57,15 @@ export interface CategoryItem {
     metrics?: CategoryMetrics;
     isFeatured?: boolean;
     featuredPriority?: number;
+    /**
+     * Whether the category is live. Declared here because `AdminCategoriesView`
+     * reads it off THIS route to render its Status column, and its fallback is
+     * `toStringValue(item.status, "Active")` — a field `CategoryDocument` does
+     * not have. So an absent `isActive` does not render "unknown", it renders
+     * **every row as "Active"**, which is the same silent-wrong-value shape the
+     * `parentId` comment in that file documents.
+     */
+    isActive?: boolean;
     /** @deprecated Use categoryType === "brand" */ isBrand?: boolean;
     seo?: CategorySeo;
     display?: CategoryDisplay;

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

@@ -16,9 +16,9 @@ export interface EventDocument extends BaseDocument {
     title: string;
     description: string;
     status: EventStatus;
-    /** Tester sandbox flag — set on the shared admin-seeded test event; swept by testerSandboxCleanup. */
+    /** Test-data flag — set on the shared admin-seeded test event; swept by testDataCleanup. */
     isTestData?: boolean;
-    /** When isTestData, the cutoff after which testerSandboxCleanup deletes this doc. */
+    /** When isTestData, the cutoff after which testDataCleanup deletes this doc. */
     testDataExpiresAt?: Date;
     startsAt: Date;
     endsAt: Date;

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

@@ -4,6 +4,7 @@
 import type { FAQCategory, FAQAnswer, FAQStats } from "../types";
 export type { FAQCategory, FAQAnswer, FAQStats } from "../types";
 import type { BaseDocument } from "../../../_internal/shared/types/base-document";
+import { extractPlaceholders } from "../../../_internal/shared/templating/placeholders";
 export interface FAQSEO {
     slug: string;
     metaTitle?: string;
@@ -53,7 +54,7 @@ export declare const faqQueryHelpers: {
     readonly byTag: (tag: string) => readonly ["tags", "array-contains", string];
     readonly byCreator: (userId: string) => readonly ["createdBy", "==", string];
 };
-export declare function extractVariablePlaceholders(text: string): string[];
+export declare const extractVariablePlaceholders: typeof extractPlaceholders;
 export declare function usesVariableInterpolation(faq: FAQDocument): boolean;
 export declare function validateFAQVariables(faq: FAQDocument, siteSettingsVariables: Record<string, string | number>): string[];
 export declare function isPopularFAQ(faq: FAQDocument): boolean;

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

@@ -2,6 +2,8 @@
  * FAQ Feature Firestore Document Types & Constants
  */
 import { generateFAQId } from "../../../utils/id-generators";
+// Imported from the DEFINING module, not a barrel (Root Cause #18).
+import { extractPlaceholders, missingPlaceholders, } from "../../../_internal/shared/templating/placeholders";
 export const FAQS_COLLECTION = "faqs";
 export const FAQS_INDEXED_FIELDS = [
     "slug",
@@ -74,21 +76,31 @@ export const faqQueryHelpers = {
     byTag: (tag) => ["tags", "array-contains", tag],
     byCreator: (userId) => ["createdBy", "==", userId],
 };
-export function extractVariablePlaceholders(text) {
-    const regex = /\{\{(\w+)\}\}/g;
-    return Array.from(text.matchAll(regex), (m) => m[1]);
-}
+/*
+ * The `{{placeholder}}` grammar moved to `_internal/shared/templating/
+ * placeholders.ts` so category description templates can share it instead of
+ * carrying a second regex (Root Cause #75).
+ *
+ * These three keep their original NAMES and signatures on purpose: they have
+ * FAQ-specific behaviour layered on the shared primitive — both gate on
+ * `useSiteSettings`, and `validateFAQVariables` merges the FAQ's own
+ * `variables` over the site-settings map. That layer is why this is a
+ * re-export-with-wrapper rather than a plain re-export, and why no FAQ call
+ * site changed.
+ */
+export const extractVariablePlaceholders = extractPlaceholders;
 export function usesVariableInterpolation(faq) {
     if (!faq.useSiteSettings)
         return false;
-    return extractVariablePlaceholders(faq.answer.text).length > 0;
+    return extractPlaceholders(faq.answer.text).length > 0;
 }
 export function validateFAQVariables(faq, siteSettingsVariables) {
     if (!faq.useSiteSettings)
         return [];
-    const placeholders = extractVariablePlaceholders(faq.answer.text);
-    const available = { ...siteSettingsVariables, ...(faq.variables || {}) };
-    return placeholders.filter((v) => !(v in available));
+    return missingPlaceholders(faq.answer.text, {
+        ...siteSettingsVariables,
+        ...(faq.variables || {}),
+    });
 }
 export function isPopularFAQ(faq) {
     const { views, helpful, notHelpful } = faq.stats;

package/dist/features/faq/utils/getHomepageFaqsCached.d.ts

@@ -0,0 +1,20 @@
+/**
+ * React.cache deduplication — one Firestore read per RSC request tree.
+ *
+ * 🛑 `getHomepageFAQs()` was called TWICE on every homepage render, from two
+ * modules that could not see each other: `src/app/[locale]/page.tsx` builds the
+ * FAQ JSON-LD from it, and `MarketplaceHomepageView` renders the FAQ section
+ * from it. Two call sites, no shared wrapper, so two real queries — and the
+ * markup and the visible content had no structural guarantee of agreeing, which
+ * is a requirement Google actually enforces.
+ *
+ * Caching the NARROWEST shared call rather than either caller is the pattern
+ * CLAUDE.md § React.cache discipline prescribes, and it is a straight copy of
+ * `getSiteSettingsGlobal` (features/admin/utils/) — which exists for exactly the
+ * same reason and is the precedent this follows.
+ *
+ * Takes no arguments on purpose: `React.cache` memoises per argument list, so a
+ * parameterised version would give each distinct call its own entry and dedupe
+ * nothing.
+ */
+export declare const getHomepageFaqsCached: () => Promise<import("..").FAQDocument[]>;

package/dist/features/faq/utils/getHomepageFaqsCached.js

@@ -0,0 +1,22 @@
+import { cache } from "react";
+import { faqsRepository } from "../repository/faqs.repository";
+/**
+ * React.cache deduplication — one Firestore read per RSC request tree.
+ *
+ * 🛑 `getHomepageFAQs()` was called TWICE on every homepage render, from two
+ * modules that could not see each other: `src/app/[locale]/page.tsx` builds the
+ * FAQ JSON-LD from it, and `MarketplaceHomepageView` renders the FAQ section
+ * from it. Two call sites, no shared wrapper, so two real queries — and the
+ * markup and the visible content had no structural guarantee of agreeing, which
+ * is a requirement Google actually enforces.
+ *
+ * Caching the NARROWEST shared call rather than either caller is the pattern
+ * CLAUDE.md § React.cache discipline prescribes, and it is a straight copy of
+ * `getSiteSettingsGlobal` (features/admin/utils/) — which exists for exactly the
+ * same reason and is the precedent this follows.
+ *
+ * Takes no arguments on purpose: `React.cache` memoises per argument list, so a
+ * parameterised version would give each distinct call its own entry and dedupe
+ * nothing.
+ */
+export const getHomepageFaqsCached = cache(() => faqsRepository.getHomepageFAQs());

package/dist/features/homepage/components/MarketplaceHomepageView.js

@@ -2,7 +2,13 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { sieveFilter, SIEVE_OP } from "@mohasinac/appkit";
 import { sortBy } from "@mohasinac/appkit";
 import { Div, Main } from "../../../ui";
-import { carouselRepository, faqsRepository, siteSettingsRepository } from "../../../repositories";
+import { carouselRepository } from "../../../repositories";
+// Both are React.cache wrappers around a single repository call, shared with
+// other readers in the same request tree (the locale layout for settings,
+// page.tsx's FAQ JSON-LD for the FAQs). Importing the repositories directly
+// here is what made each of those a second Firestore read.
+import { getSiteSettingsGlobal } from "../../admin/utils/getSiteSettingsGlobal";
+import { getHomepageFaqsCached } from "../../faq/utils/getHomepageFaqsCached";
 import { safeRead } from "../../../errors/safe-read";
 import { fetchLiveStats } from "../lib/live-stats";
 import { renderSection, AnnouncementBar } from "../lib/section-renderer";
@@ -46,7 +52,10 @@ export async function MarketplaceHomepageView({ adSlots, newsletterFormSlot, onB
     const slides = await safeRead(() => carouselRepository.getActiveSlides(), {
         route: "/", key: "homepage.carouselSlides", fallback: [],
     });
-    const siteSettings = await safeRead(() => siteSettingsRepository.getSingleton(), {
+    // getSiteSettingsGlobal, not the repository directly — the locale layout and
+    // generateMetadata already read the same singleton through it, so this is one
+    // Firestore read for the whole request tree instead of a second one.
+    const siteSettings = await safeRead(() => getSiteSettingsGlobal(), {
         route: "/", key: "homepage.siteSettings", fallback: null,
     });
     // The fallback used to be a hardcoded seasonal Pokémon TCG discount, which
@@ -58,7 +67,8 @@ export async function MarketplaceHomepageView({ adSlots, newsletterFormSlot, onB
         safeRead(() => homepageSectionsRepository.getEnabledSections(), {
             route: "/", key: "homepage.enabledSections", fallback: [],
         }),
-        safeRead(() => faqsRepository.getHomepageFAQs(), {
+        // Shared with the FAQ JSON-LD built in src/app/[locale]/page.tsx — one read.
+        safeRead(() => getHomepageFaqsCached(), {
             route: "/", key: "homepage.faqs", fallback: [],
         }),
     ]);

package/dist/features/homepage/lib/live-stats.js

@@ -47,16 +47,26 @@ export async function fetchLiveStats(requests) {
             .catch((err) => { void normalizeError(err); serverLogger.warn("live-stats: total_orders query failed — stat omitted", { error: err instanceof Error ? err.message : String(err) }); }));
     }
     if (neededPresets.has("total_reviews") || neededPresets.has("platform_rating")) {
-        tasks.push(reviewRepository.findAll()
-            .then((res) => {
-            const all = Array.isArray(res) ? res : (res?.data ?? []);
-            const approved = all.filter((r) => !r.status || r.status === "approved");
+        tasks.push(
+        /*
+         * 🛑 One aggregation, ~1 read — was `findAll()`, an UNBOUNDED full-collection
+         * scan of `reviews` on every cold homepage render, whose entire output was
+         * these two strings. Billed one read per document, it was the largest single
+         * Firestore read on the site (Hobby free tier is 50K reads/day, and the
+         * project measured 2.1M/week).
+         *
+         * The dropped `!r.status ||` branch was dead: `status` is a REQUIRED field
+         * defaulting to `"pending"` (features/reviews/schemas/firestore.ts), so no
+         * stored review lacks it, and treating a missing status as approved would
+         * have counted unmoderated reviews anyway.
+         */
+        reviewRepository.getApprovedSiteRatingSummary()
+            .then(({ count, average }) => {
             if (neededPresets.has("total_reviews")) {
-                resolvedPresets.total_reviews = String(approved.length);
+                resolvedPresets.total_reviews = String(count);
             }
-            if (neededPresets.has("platform_rating") && approved.length > 0) {
-                const avg = approved.reduce((sum, r) => sum + (r.rating ?? 0), 0) / approved.length;
-                resolvedPresets.platform_rating = avg.toFixed(1) + "★";
+            if (neededPresets.has("platform_rating") && average !== null) {
+                resolvedPresets.platform_rating = average.toFixed(1) + "★";
             }
         })
             .catch((err) => { void normalizeError(err); serverLogger.warn("live-stats: reviews/rating query failed — stat omitted", { error: err instanceof Error ? err.message : String(err) }); }));

package/dist/features/media/MediaImage.js

@@ -4,7 +4,7 @@ import Image from "next/image";
 import { useEffect, useRef, useState } from "react";
 import { Div, Row, Span } from "../../ui";
 import { ROUNDED_MAP, SHADOW_MAP } from "../../ui/components/surface-tokens";
-import { resolveMediaUrl } from "../../utils/media-url";
+import { MEDIA_PROXY_PREFIX, resolveMediaUrl } from "../../utils/media-url";
 const SIZE_HINTS = {
     thumbnail: "(max-width: 640px) 80px, (max-width: 1024px) 96px, 112px",
     card: "(max-width: 640px) 50vw, (max-width: 1024px) 33vw, 25vw",
@@ -32,6 +32,23 @@ const FALLBACK_ICONS = {
 // icon, instead of failing permanently on the very first request.
 const MAX_LOAD_RETRIES = 3;
 const RETRY_BACKOFF_MS = [600, 1200, 2400];
+/**
+ * Only `/media/<slug>` may be retried.
+ *
+ * 🛑 The retry appends `?retry=N`, which mints a BRAND-NEW CDN cache key that is
+ * guaranteed cold — so a failing image costs up to 4 cold function invocations
+ * instead of 1, on precisely the images that are already flaky. That is a real
+ * cost multiplier and it suspended this project once (HTTP 402, 2026-10-09).
+ *
+ * It is worth paying for our own Storage objects, because the post-upload race
+ * above is genuine and transient — retrying actually succeeds. It is NOT worth
+ * paying for `/api/media/ext`: there is no upload, the upstream is a third party
+ * we do not control, and an upstream that just failed will almost certainly fail
+ * again. Those fall straight through to the fallback icon on the first error.
+ */
+function isRetryableSrc(resolvedSrc) {
+    return resolvedSrc.startsWith(MEDIA_PROXY_PREFIX);
+}
 /** Resolve every URL in a comma-separated srcset string through the media proxy. */
 function resolveSrcSet(input) {
     return input
@@ -78,7 +95,7 @@ export function MediaImage({ src, alt, size = "card", priority = false, loading,
         className ?? "",
     ].filter(Boolean).join(" ");
     const handleError = () => {
-        if (retryCount < MAX_LOAD_RETRIES) {
+        if (resolvedSrc && isRetryableSrc(resolvedSrc) && retryCount < MAX_LOAD_RETRIES) {
             retryTimeoutRef.current = setTimeout(() => {
                 setRetryCount((count) => count + 1);
             }, RETRY_BACKOFF_MS[retryCount]);

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

@@ -180,6 +180,25 @@ export interface OrderDocumentItem {
     totalPrice: number;
     /** SB8-F â€" set when the item is a prize-draw entry; drives the reveals badge. */
     listingType?: ListingType;
+    /**
+     * The product's LEAF category, snapshotted at order time (C1).
+     *
+     * 🛑 A SNAPSHOT, not a join, and not for performance alone. `priceIndexRollup`
+     * needs to know which category band a realised sale belongs to, and this
+     * interface carried no taxonomy field at all — `bundleCategorySlug` is a
+     * bundle key, not a category — so the only route was a full products scan
+     * per run, which answers nothing for an item whose product has since been
+     * deleted.
+     *
+     * It is also the correct answer rather than the cheap one: a product
+     * re-categorised next year must not retroactively move last year's sale into
+     * a band it was never part of. Same reasoning as the `hsnCode` / `gstRate` /
+     * `finalSale` snapshots below — a past sale's facts are fixed.
+     *
+     * Absent on every order written before C1, which is why the rollup keeps the
+     * products-map fallback rather than treating absence as "no category".
+     */
+    categorySlug?: string;
     /** SB8-F â€" per-item reveal status; flips through pending â†' open â†' revealed/closed. */
     prizeRevealStatus?: "pending" | "open" | "closed" | "revealed";
     /** Set when the buyer cancels this specific line item post-order (partial cancellation). */
@@ -358,6 +377,57 @@ export interface OrderDocument extends BaseDocument {
     sgst?: number;
     /** Inter-state: buyer and seller/store pickup address are in different states. */
     igst?: number;
+    /**
+     * Taxable value of 0%-rated (EXEMPT) goods in this order — live plants and
+     * animals. **Not** part of `taxableAmount`, which covers positively-rated
+     * slices only.
+     *
+     * 🛑 Without it a mixed exempt/taxed order cannot reconcile its own invoice:
+     * `sumGroupGst` skipped exempt slices entirely, so `taxableAmount` excluded
+     * them while `items[]` included them, and the Taxable column could never
+     * sum to the summary. Exempt is a real, reportable state (nil-rated supply),
+     * not an absence.
+     */
+    exemptAmount?: number;
+    /**
+     * Per-rate rollup — taxable value and tax for each distinct `gstRate` in the
+     * order.
+     *
+     * 🛑 Required for a Rule 46-compliant invoice, which asks for taxable value
+     * and tax **per rate**. The aggregate `taxableAmount`/`gstAmount`/cgst/sgst/
+     * igst fields above lose that dimension, so a mixed 5% + 18% order could not
+     * produce a compliant document without re-deriving the split downstream —
+     * i.e. a second implementation of the loop that already computed it.
+     */
+    gstByRate?: Array<{
+        gstRate: number;
+        taxableAmount: number;
+        cgst: number;
+        sgst: number;
+        igst: number;
+        gstAmount: number;
+    }>;
+    /**
+     * OUR GST registration as it stood at the moment of supply — LetItRip is the
+     * seller of record and invoices under its own GSTIN.
+     *
+     * 🛑 Snapshotted for two independent reasons, and both matter.
+     *
+     * **Compliance**: changing our registered details must never rewrite an
+     * invoice already issued. Same discipline as `items[].hsnCode` / `gstRate` /
+     * `finalSale`, and the same reason `TaxCodeDocument` edits change future
+     * derivations only.
+     *
+     * **Access**: `gst` sits in `PRIVATE_SITE_FIELDS` — withheld from the public
+     * site-settings projection precisely because an earlier deny-list version
+     * shipped the GSTIN and registered legal name to anonymous callers (Root
+     * Cause #70). So the invoice page cannot read it from site settings, and it
+     * should not: the buyer is entitled to the GSTIN *on their own invoice*,
+     * which is an authenticated per-order read, not public data.
+     */
+    supplierGstin?: string;
+    supplierLegalName?: string;
+    supplierAddress?: string;
     emiEnabled?: boolean;
     /** Number of monthly installments the buyer chose (2–6). */
     emiTenureMonths?: number;

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

@@ -53,6 +53,18 @@ export interface OrderItem {
      * gate reads the document, so this is a rendering hint only.
      */
     finalSale?: boolean;
+    /**
+     * HSN code and GST rate, snapshotted onto the order item at purchase.
+     *
+     * 🛑 Surfaced here because the INVOICE needs them per line and could not
+     * previously get them: `orderDocumentToOrder` mapped `tax: doc.gstAmount`
+     * and nothing else tax-related, so the buyer-facing invoice rendered
+     * `["Item", "Qty", "Price"]` and one aggregate Tax row — not because the
+     * renderer was lazy, but because the adapter never handed it a rate, an HSN
+     * or a split to show. Root Cause #57's exact shape.
+     */
+    hsnCode?: string;
+    gstRate?: 0 | 5 | 12 | 18 | 28;
 }
 /**
  * One entry on an order's timeline — the client-facing shape of
@@ -100,7 +112,50 @@ export interface Order {
     subtotal: number;
     shippingCost?: number;
     discount?: number;
+    /** Total GST — product GST plus the GST on our platform fee. */
     tax?: number;
+    /**
+     * The GST breakdown the INVOICE needs, and which the adapter did not map
+     * until 2026-10-10 — so `/user/orders/[id]/invoice` had no GSTIN, no HSN
+     * column, no rate column and one undifferentiated "Tax (GST)" row, and was
+     * therefore not Rule 46-compliant in any respect.
+     *
+     * 🛑 `taxableAmount` excludes `exemptAmount`: a 0%-rated supply is a real
+     * reportable state, not an absence, and keeping them separate is what lets
+     * the invoice's columns reconcile against its own summary.
+     */
+    taxableAmount?: number;
+    exemptAmount?: number;
+    cgst?: number;
+    sgst?: number;
+    igst?: number;
+    /**
+     * Taxable value and tax PER RATE — what Rule 46 actually asks for.
+     *
+     * ✅ This is also why no per-item `gstAmount` was added. Rule 46 requires the
+     * tax amount per **rate**, not per **line**; the per-line requirements are
+     * HSN, quantity, taxable value and rate, all of which the item already
+     * carries or derives from `price × quantity`. A per-item tax amount would be
+     * a denormalised mirror of what this array already holds — Root Cause #42's
+     * shape — so it was deliberately NOT added.
+     */
+    gstByRate?: Array<{
+        gstRate: number;
+        taxableAmount: number;
+        cgst: number;
+        sgst: number;
+        igst: number;
+        gstAmount: number;
+    }>;
+    /**
+     * Our GST registration as snapshotted on this order. A tax invoice without
+     * the supplier's GSTIN is not a tax invoice — and the invoice page cannot
+     * read it from site settings, because `gst` is in `PRIVATE_SITE_FIELDS`
+     * after an earlier deny-list projection shipped it publicly (Root Cause #70).
+     */
+    supplierGstin?: string;
+    supplierLegalName?: string;
+    supplierAddress?: string;
     total: number;
     currency: string;
     /**

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

@@ -15,15 +15,6 @@ export interface ProductListActionParams {
 export type ProductListResult = FirebaseSieveResult<ProductDocument>;
 export declare function listProducts(params?: ProductListActionParams): Promise<ProductListResult>;
 export declare function getProductById(id: string): Promise<ProductDocument | null>;
-/**
- * Featured items for the homepage's generic "Featured Products" strip.
- *
- * Scoped to `GENERIC_PRODUCT_LISTING_TYPES` for the same reason `/products` is:
- * the homepage already has dedicated Live Auctions, Pre-Orders and Prize Draws
- * sections, so leaving this unscoped put the same item in two strips on one
- * page — and an auction rendered as a generic product card shows Buy-Now chrome
- * instead of bid affordances.
- */
 export declare function getFeaturedProducts(pageSize?: number): Promise<ProductListResult>;
 /**
  * The soonest-ending LIVE auctions.

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

@@ -73,6 +73,28 @@ function toListResult(result, pageSize) {
  * page — and an auction rendered as a generic product card shows Buy-Now chrome
  * instead of bid affordances.
  */
+/**
+ * How many documents a fixed-size homepage strip may read.
+ *
+ * 🛑 These strips land on `listPublicProducts`' in-memory window path — every
+ * anonymous viewer sets `hidesTestData`, which forces it — and that path pins
+ * the fetch to 50 documents regardless of the requested `pageSize`. So
+ * `getFeaturedProducts(12)` read 51 to render 12, and the homepage does this
+ * four times: ~200 reads for 44 cards, against a 50K-reads/day free tier that
+ * the project was exceeding 6× (2.1M/week, measured 2026-10-09).
+ *
+ * Headroom is genuinely required, not optional: availability and test-data are
+ * per-row predicates applied AFTER the fetch, so a window equal to `pageSize`
+ * would under-fill the strip the moment one row is unavailable. 2× with a floor
+ * of +8 absorbs that while still cutting the read roughly in half.
+ *
+ * Deliberately NOT derived inside `listPublicProducts` from `pageSize` — a
+ * browse page must keep the full 50 so it can page deeply, and silently
+ * shrinking its window would drop rows from page 2 onward.
+ */
+function featuredWindow(pageSize) {
+    return Math.max(pageSize * 2, pageSize + 8);
+}
 export async function getFeaturedProducts(pageSize = 8) {
     return toListResult(await listPublicProducts({
         featured: true,
@@ -81,6 +103,7 @@ export async function getFeaturedProducts(pageSize = 8) {
         sorts: sortBy("createdAt", "DESC"),
         page: 1,
         pageSize,
+        windowSize: featuredWindow(pageSize),
     }), pageSize);
 }
 /**
@@ -103,6 +126,7 @@ export async function getFeaturedAuctions(pageSize = 6) {
         sorts: sortBy(PRODUCT_FIELDS.AUCTION_END_DATE, "ASC"),
         page: 1,
         pageSize,
+        windowSize: featuredWindow(pageSize),
     }), pageSize);
 }
 export async function getLatestProducts(pageSize = 12) {
@@ -138,6 +162,7 @@ export async function getFeaturedPreOrders(pageSize = 6) {
         sorts: sortBy(PRODUCT_FIELDS.PRE_ORDER_DELIVERY_DATE, "ASC"),
         page: 1,
         pageSize,
+        windowSize: featuredWindow(pageSize),
     }), pageSize);
 }
 export async function getLatestPreOrders(pageSize = 12) {

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

@@ -8,7 +8,6 @@ export declare const PRODUCT_SORT_VALUES: {
     readonly PRICE_LOW: "price";
     readonly PRICE_HIGH: "-price";
     readonly RATING_HIGH: "-avgRating";
-    readonly POPULAR: "-viewCount";
     readonly NAME_AZ: "title";
     readonly NAME_ZA: "-title";
 };

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

@@ -6,7 +6,11 @@ export const PRODUCT_SORT_VALUES = {
     PRICE_LOW: "price",
     PRICE_HIGH: "-price",
     RATING_HIGH: "-avgRating",
-    POPULAR: "-viewCount",
+    // 🛑 `POPULAR: "-viewCount"` removed 2026-10-10 — `viewCount` is on no
+    // document (0/72 products, 0/58 categories) and nothing writes it, so a
+    // Firestore orderBy on it excludes every row. Verified: 0 results against a
+    // valid index. See STANDARD_SORT_OPTIONS for the full writeup.
+    // `RATING_HIGH` above is fine by contrast — `avgRating` is present on 72/72.
     NAME_AZ: "title",
     NAME_ZA: "-title",
 };

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

@@ -20,5 +20,11 @@ export async function ArtStickersListView({ searchParams = {} }) {
         // about the default view (Root Cause #30).
         ...defaultAvailabilityForListingTypes(ART_STICKERS_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: "Art & Stickers" }), _jsx(Text, { className: "mt-1", color: "muted", size: "sm", children: "Original art prints and sticker packs from independent sellers" })] }) }), _jsxs(Container, { size: "xl", padding: "x-md", children: [_jsx(AdSlot, { id: "listing-sidebar-top", className: "mb-4 mt-4" }), _jsx(ProductsIndexListing, { initialData: result ?? null, listingTypes: ART_STICKERS_LISTING_TYPES, typeTabs: ART_STICKERS_TYPE_FILTER_TABS, searchPlaceholder: "Search art & stickers..." }), _jsx(AdSlot, { id: "listing-sidebar-bottom", className: "mt-8" })] })] }));
+    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: "Art & Stickers" }), _jsx(Text, { className: "mt-1", color: "muted", size: "sm", children: "Original art prints and sticker packs from independent sellers" })] }) }), _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 froze an empty grid. See ProductsIndexPageView.
+                    , { 
+                        // `undefined`, not `null` — React Query treats null as defined data,
+                        // so a failed query froze an empty grid. See ProductsIndexPageView.
+                        initialData: result ?? undefined, listingTypes: ART_STICKERS_LISTING_TYPES, typeTabs: ART_STICKERS_TYPE_FILTER_TABS, searchPlaceholder: "Search art & stickers..." }), _jsx(AdSlot, { id: "listing-sidebar-bottom", className: "mt-8" })] })] }));
 }