@mohasinac/appkit 4.58.0 → 4.60.0

package/dist/features/categories/repository/price-observation.repository.d.ts

@@ -0,0 +1,166 @@
+/**
+ * Price Observations — one DATED sighting of one price for one leaf.
+ *
+ * ## Why this collection has to exist at all
+ *
+ * The competitor crawl of 2026-10 survives only as a summarised markdown table:
+ * p25/median/p75 per GENERATION, and a single `asOf` for the whole thing. That
+ * shape makes three questions permanently unanswerable, and all three were
+ * asked:
+ *
+ *   "most common price"     a mode needs the observations, not a summary of them
+ *   "last six months"       one crawl date cannot yield a window
+ *   "what does THIS bey go  a generation band cannot distinguish Dragoon MS
+ *    for"                   from Strata Dragoon MS — different beys, one number
+ *
+ * None of those is a rendering problem, which is why no amount of relabelling
+ * fixed them. They are the shape of the stored data, and this is that shape
+ * changed: the row is the unit, the summary is derived, and the derivation can
+ * be re-run with a different window whenever the question changes.
+ *
+ * ## 🛑 A sibling collection, never a field on `categories`
+ *
+ * Identical reasoning to `price-index.repository.ts`, and it is not theoretical.
+ * `onCategoryWrite` is a `documentWritten` trigger on `categories`, so a job
+ * writing a band there re-triggers it per document — Root Cause #92's shape,
+ * which produced **1,017,548 invocations in 24 hours** against a 2M/month
+ * allowance and blocked `firebase deploy` with a billing denial. Worse here:
+ * `notifyRevalidate` fires on every category write, so each rolled-up band
+ * would drop that category page's ISR entry, on a project already paused once
+ * for exceeding ISR writes by 15.5×.
+ *
+ * ## 🛑 `sourceKey` is OPAQUE, by instruction
+ *
+ * The owner's requirement is that competitors are not named on the surface. The
+ * honest way to meet that is to not carry the name into the record a renderer
+ * can reach — not to carry it and remember never to print it, which is one
+ * careless `{...row}` away from publishing (Root Cause #70: a public payload
+ * built by spreading a document publishes every field nobody thought to delete).
+ *
+ * So the stored value is a stable opaque key (`src-a`, `src-b`, …). It still
+ * does the two jobs provenance needs — telling two sources apart, and letting
+ * one be re-crawled or retracted wholesale — without the name being present to
+ * leak. The key↔name mapping is operator knowledge, kept out of the database.
+ *
+ * ## Shape
+ *
+ *   priceObservations/{observationId}
+ *
+ * One flat collection, no subcollections. Rows are queried by `categoryId` and
+ * `seenAt` and never listed wholesale, so the composite index
+ * `(categoryId, seenAt desc)` is the only one it needs.
+ *
+ * @tag domain:price-index
+ * @tag layer:repository
+ * @tag pattern:repository
+ * @tag access:server-only
+ * @tag consumers:marketPriceRollup,price-observations CLI
+ * @tag sideEffects:writes priceObservations
+ */
+import { BaseRepository } from "../../../providers/db-firebase";
+/**
+ * What kind of event the sighting was.
+ *
+ * 🛑 The distinction `price-bands.md` is built around: *"a sold-out row proves
+ * the item is GONE, not that it sold at that price"*, with 76–93% of crawled
+ * listings sold out. An ask and a sale are different events and a band that
+ * blends them describes neither — so the kind is recorded per row and the
+ * rollup groups on it rather than averaging across it.
+ */
+export type PriceObservationKind = "ask" | "sale";
+export interface PriceObservationDocument {
+    id: string;
+    /**
+     * The leaf this prices — a MODEL leaf wherever the sighting names a model.
+     *
+     * 🛑 This is the field that makes the whole collection worth building. The
+     * seeded bands hang on ~60 generation leaves, so every one of the 1,904 model
+     * leaves inherits a number measured for its entire era. Recording the model
+     * id is what lets Dragoon MS and Strata Dragoon MS hold different prices,
+     * which they do in the real market.
+     */
+    categoryId: string;
+    /** Decimal rupees, tax-inclusive — `PRICE_GUIDANCE_TAX_BASIS`. */
+    amount: number;
+    currency: "INR";
+    kind: PriceObservationKind;
+    /**
+     * When the price was SEEN, not when the row was written.
+     *
+     * 🛑 These come apart and the gap is the entire point. Back-filling a
+     * two-year-old crawl writes rows today that describe 2024 — using
+     * `createdAt` as the date would file every one of them inside the six-month
+     * window and report stale prices as current, which is the failure this
+     * collection exists to make impossible.
+     */
+    seenAt: Date;
+    /**
+     * `ProductDocument.condition` where the sighting stated one.
+     *
+     * Absent means NOT STATED — never "new". Condition is the dominant price
+     * variable in collectibles (hobson's "Without Box" group runs ₹599 against
+     * ₹4,499 for the same figures boxed), so guessing it would be guessing the
+     * price. Captured now even though the v1 rollup does not slice on it, because
+     * a column nobody recorded cannot be back-filled later.
+     */
+    condition?: string;
+    /** True when the listing was already sold out when seen. */
+    soldOut?: boolean;
+    /** Opaque, stable, never a competitor name. See the header. */
+    sourceKey: string;
+    /** Free-text operator note. Never rendered publicly. */
+    note?: string;
+    createdAt: Date;
+}
+export declare const PRICE_OBSERVATION_COLLECTION = "priceObservations";
+/**
+ * Hard ceiling on one leaf's observation read.
+ *
+ * A leaf with more sightings than this has plenty for a stable band, so the cap
+ * costs no accuracy — it exists so a mis-tagged import cannot turn one rollup
+ * iteration into an unbounded read (Rule #6).
+ */
+export declare const PRICE_OBSERVATION_SCAN_LIMIT = 500;
+export declare class PriceObservationRepository extends BaseRepository<PriceObservationDocument> {
+    constructor();
+    /**
+     * Every sighting for one leaf, newest first, bounded.
+     *
+     * 🛑 Ordered by `seenAt` and NOT filtered by it. The rollup needs both the
+     * recent window and the full history — it decides between them itself
+     * (`computeMarketStats`), because that decision has to be made once, in one
+     * place, or the job and the renderer will disagree about which window a
+     * figure came from. Pushing a date filter down here would make the historic
+     * fallback impossible without a second query.
+     *
+     * 🛑 `orderBy("seenAt")` excludes any document LACKING the field — the
+     * optional-field trap of Root Cause #100, where a store's reviews read as
+     * zero because `itemsSold` had never been written. `seenAt` is required by
+     * the write path below precisely so that exclusion can never bite.
+     */
+    findForLeaf(categoryId: string, limit?: number): Promise<PriceObservationDocument[]>;
+    /**
+     * Every leaf that has at least one observation.
+     *
+     * 🛑 Enumerates the ENTITIES, not the events — Root Cause #102's lesson, from
+     * a reconciler that built its tally from products that exist rather than
+     * categories that exist and so could only ever add. The rollup iterates this
+     * list, so a leaf whose last observation was retracted is still visited and
+     * its stale band cleared.
+     *
+     * `.select()` fetches no field data; only the ids are needed to group.
+     */
+    listLeafIdsWithObservations(scanLimit?: number): Promise<string[]>;
+    /**
+     * Record a sighting.
+     *
+     * 🛑 `seenAt` is required from the caller and is NEVER defaulted to the write
+     * time. `BaseRepository.create` stamps `createdAt` itself — which is why the
+     * two fields exist separately and why this signature cannot accept one in
+     * place of the other. Back-filling an old crawl writes rows today that
+     * describe last year; conflating the two dates would file every one of them
+     * inside the six-month window.
+     */
+    record(input: Omit<PriceObservationDocument, "id" | "createdAt" | "updatedAt" | "currency">): Promise<PriceObservationDocument>;
+}
+export declare const priceObservationRepository: PriceObservationRepository;

package/dist/features/categories/repository/price-observation.repository.js

@@ -0,0 +1,132 @@
+/**
+ * Price Observations — one DATED sighting of one price for one leaf.
+ *
+ * ## Why this collection has to exist at all
+ *
+ * The competitor crawl of 2026-10 survives only as a summarised markdown table:
+ * p25/median/p75 per GENERATION, and a single `asOf` for the whole thing. That
+ * shape makes three questions permanently unanswerable, and all three were
+ * asked:
+ *
+ *   "most common price"     a mode needs the observations, not a summary of them
+ *   "last six months"       one crawl date cannot yield a window
+ *   "what does THIS bey go  a generation band cannot distinguish Dragoon MS
+ *    for"                   from Strata Dragoon MS — different beys, one number
+ *
+ * None of those is a rendering problem, which is why no amount of relabelling
+ * fixed them. They are the shape of the stored data, and this is that shape
+ * changed: the row is the unit, the summary is derived, and the derivation can
+ * be re-run with a different window whenever the question changes.
+ *
+ * ## 🛑 A sibling collection, never a field on `categories`
+ *
+ * Identical reasoning to `price-index.repository.ts`, and it is not theoretical.
+ * `onCategoryWrite` is a `documentWritten` trigger on `categories`, so a job
+ * writing a band there re-triggers it per document — Root Cause #92's shape,
+ * which produced **1,017,548 invocations in 24 hours** against a 2M/month
+ * allowance and blocked `firebase deploy` with a billing denial. Worse here:
+ * `notifyRevalidate` fires on every category write, so each rolled-up band
+ * would drop that category page's ISR entry, on a project already paused once
+ * for exceeding ISR writes by 15.5×.
+ *
+ * ## 🛑 `sourceKey` is OPAQUE, by instruction
+ *
+ * The owner's requirement is that competitors are not named on the surface. The
+ * honest way to meet that is to not carry the name into the record a renderer
+ * can reach — not to carry it and remember never to print it, which is one
+ * careless `{...row}` away from publishing (Root Cause #70: a public payload
+ * built by spreading a document publishes every field nobody thought to delete).
+ *
+ * So the stored value is a stable opaque key (`src-a`, `src-b`, …). It still
+ * does the two jobs provenance needs — telling two sources apart, and letting
+ * one be re-crawled or retracted wholesale — without the name being present to
+ * leak. The key↔name mapping is operator knowledge, kept out of the database.
+ *
+ * ## Shape
+ *
+ *   priceObservations/{observationId}
+ *
+ * One flat collection, no subcollections. Rows are queried by `categoryId` and
+ * `seenAt` and never listed wholesale, so the composite index
+ * `(categoryId, seenAt desc)` is the only one it needs.
+ *
+ * @tag domain:price-index
+ * @tag layer:repository
+ * @tag pattern:repository
+ * @tag access:server-only
+ * @tag consumers:marketPriceRollup,price-observations CLI
+ * @tag sideEffects:writes priceObservations
+ */
+import { BaseRepository } from "../../../providers/db-firebase/index.js";
+export const PRICE_OBSERVATION_COLLECTION = "priceObservations";
+/**
+ * Hard ceiling on one leaf's observation read.
+ *
+ * A leaf with more sightings than this has plenty for a stable band, so the cap
+ * costs no accuracy — it exists so a mis-tagged import cannot turn one rollup
+ * iteration into an unbounded read (Rule #6).
+ */
+export const PRICE_OBSERVATION_SCAN_LIMIT = 500;
+export class PriceObservationRepository extends BaseRepository {
+    constructor() {
+        super(PRICE_OBSERVATION_COLLECTION);
+    }
+    /**
+     * Every sighting for one leaf, newest first, bounded.
+     *
+     * 🛑 Ordered by `seenAt` and NOT filtered by it. The rollup needs both the
+     * recent window and the full history — it decides between them itself
+     * (`computeMarketStats`), because that decision has to be made once, in one
+     * place, or the job and the renderer will disagree about which window a
+     * figure came from. Pushing a date filter down here would make the historic
+     * fallback impossible without a second query.
+     *
+     * 🛑 `orderBy("seenAt")` excludes any document LACKING the field — the
+     * optional-field trap of Root Cause #100, where a store's reviews read as
+     * zero because `itemsSold` had never been written. `seenAt` is required by
+     * the write path below precisely so that exclusion can never bite.
+     */
+    async findForLeaf(categoryId, limit = PRICE_OBSERVATION_SCAN_LIMIT) {
+        const snap = await this.getCollection()
+            .where("categoryId", "==", categoryId)
+            .orderBy("seenAt", "desc")
+            .limit(limit)
+            .get();
+        return snap.docs.map((d) => this.mapDoc(d));
+    }
+    /**
+     * Every leaf that has at least one observation.
+     *
+     * 🛑 Enumerates the ENTITIES, not the events — Root Cause #102's lesson, from
+     * a reconciler that built its tally from products that exist rather than
+     * categories that exist and so could only ever add. The rollup iterates this
+     * list, so a leaf whose last observation was retracted is still visited and
+     * its stale band cleared.
+     *
+     * `.select()` fetches no field data; only the ids are needed to group.
+     */
+    async listLeafIdsWithObservations(scanLimit = 20000) {
+        const snap = await this.getCollection().select("categoryId").limit(scanLimit).get();
+        const ids = new Set();
+        for (const doc of snap.docs) {
+            const id = doc.data().categoryId;
+            if (id)
+                ids.add(id);
+        }
+        return [...ids];
+    }
+    /**
+     * Record a sighting.
+     *
+     * 🛑 `seenAt` is required from the caller and is NEVER defaulted to the write
+     * time. `BaseRepository.create` stamps `createdAt` itself — which is why the
+     * two fields exist separately and why this signature cannot accept one in
+     * place of the other. Back-filling an old crawl writes rows today that
+     * describe last year; conflating the two dates would file every one of them
+     * inside the six-month window.
+     */
+    async record(input) {
+        return this.create({ ...input, currency: "INR" });
+    }
+}
+export const priceObservationRepository = new PriceObservationRepository();

package/dist/features/events/components/EventSaleBanner.js

@@ -16,5 +16,5 @@ export function EventSaleBanner({ discountPercent, couponCode, title, subtitle,
     const href = filterParam
         ? `${ROUTES.PUBLIC.PRODUCTS}?${encodeURIComponent(filterParam.key)}=${encodeURIComponent(filterParam.value)}`
         : `${ROUTES.PUBLIC.PRODUCTS}?onSale=true`;
-    return (_jsx(Section, { color: "inverse", tone: "accent-banner", className: `${__P.p6}`, rounded: "2xl", shadow: "lg", children: _jsxs(Stack, { gap: "md", children: [_jsxs(Stack, { gap: "xs", children: [_jsx(Heading, { level: 2, weight: "bold", size: "3xl", children: headline }), subtitle ? _jsx(Text, { color: "inverse", className: "/90", size: "base", children: subtitle }) : null] }), couponCode ? (_jsxs(Div, { layout: "inline-flex", gap: "3", align: "center", className: "backdrop-blur", surface: "default", paddingY: "y-xs", paddingX: "x-md", rounded: "lg", children: [_jsx(Span, { size: "xs", className: "tracking-wide opacity-80", transform: "uppercase", children: "Code" }), _jsx(Span, { size: "lg", weight: "bold", className: "font-mono", children: couponCode })] })) : null, _jsx(Div, { children: _jsx(Link, { href: href, children: _jsx(Button, { variant: "secondary", children: "Shop the sale" }) }) })] }) }));
+    return (_jsx(Section, { color: "inverse", tone: "accent-banner", className: `${__P.p6}`, rounded: "2xl", shadow: "lg", children: _jsxs(Stack, { gap: "md", children: [_jsxs(Stack, { gap: "xs", children: [_jsx(Heading, { level: 2, weight: "bold", size: "3xl", children: headline }), subtitle ? _jsx(Text, { color: "inverse-muted", size: "base", children: subtitle }) : null] }), couponCode ? (_jsxs(Div, { layout: "inline-flex", gap: "3", align: "center", className: "backdrop-blur", surface: "default", paddingY: "y-xs", paddingX: "x-md", rounded: "lg", children: [_jsx(Span, { size: "xs", className: "tracking-wide opacity-80", transform: "uppercase", children: "Code" }), _jsx(Span, { size: "lg", weight: "bold", className: "font-mono", children: couponCode })] })) : null, _jsx(Div, { children: _jsx(Link, { href: href, children: _jsx(Button, { variant: "secondary", children: "Shop the sale" }) }) })] }) }));
 }

package/dist/features/events/components/EventStatusBadge.js

@@ -1,7 +1,7 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { Span } from "../../../ui/index.js";
 const STATUS_MAP = {
-    draft: { label: "Draft", color: "bg-[var(--appkit-color-surface)] bg-[var(--appkit-color-surface-elevated)] text-[var(--appkit-color-text-muted)]" },
+    draft: { label: "Draft", color: "bg-[var(--appkit-color-surface-elevated)] text-[var(--appkit-color-text-muted)]" },
     active: { label: "Active", color: "bg-success-surface text-success" },
     paused: { label: "Paused", color: "bg-warning-surface text-warning" },
     ended: { label: "Ended", color: "bg-error-surface text-error" },

package/dist/features/faq/components/FAQAccordion.js

@@ -2,8 +2,9 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useState } from "react";
 import { Button, Div, RichText, Row, Span, Tabs, TabsList, TabsTrigger, Text } from "../../../ui/index.js";
+import { RecordOwnerQuickActions } from "../../admin/components/RecordOwnerQuickActions.js";
 function FAQAccordionItem({ faq, isOpen, onToggle, renderExpandedFooter, }) {
-    return (_jsxs(Div, { className: "border-b border-neutral-200 last:border-0", children: [_jsxs(Button, { variant: "ghost", onClick: onToggle, "aria-expanded": isOpen, justify: "between", className: "w-full gap-[1rem] py-[1rem] text-left text-[0.875rem] font-[500] text-[var(--appkit-color-text)] dark:text-[var(--appkit-color-text)] transition hover:text-primary", children: [_jsx(Span, { children: faq.question }), _jsx(Span, { className: `flex-shrink-0 transition-transform ${isOpen ? "rotate-180" : ""}`, children: _jsx("svg", { width: "16", height: "16", viewBox: "0 0 16 16", fill: "none", "aria-hidden": "true", children: _jsx("path", { d: "M4 6l4 4 4-4", stroke: "currentColor", strokeWidth: "1.5", strokeLinecap: "round", strokeLinejoin: "round" }) }) })] }), isOpen && (_jsxs(Div, { textSize: "sm", className: "text-[var(--appkit-color-text-muted)]", padding: "b-md", children: [faq.tags && faq.tags.length > 0 && (_jsx(Row, { wrap: true, gap: "sm", className: "mb-3", children: faq.tags.map((tag) => (_jsx(Span, { className: "bg-[var(--appkit-color-surface)] py-[0.25rem] text-[var(--appkit-color-text-muted)]", rounded: "md", padding: "x-xs", size: "xs", children: tag }, tag))) })), faq.answer.format === "html" ? (_jsx(RichText, { html: faq.answer.text, className: "prose-sm" })) : (_jsx(Text, { className: "whitespace-pre-line", children: faq.answer.text })), renderExpandedFooter?.(faq)] }))] }));
+    return (_jsxs(Div, { className: "border-b border-neutral-200 last:border-0", children: [_jsxs(Button, { variant: "ghost", onClick: onToggle, "aria-expanded": isOpen, justify: "between", className: "w-full gap-[1rem] py-[1rem] text-left text-[0.875rem] font-[500] text-[var(--appkit-color-text)] dark:text-[var(--appkit-color-text)] transition hover:text-primary", children: [_jsx(Span, { children: faq.question }), _jsx(Span, { className: `flex-shrink-0 transition-transform ${isOpen ? "rotate-180" : ""}`, children: _jsx("svg", { width: "16", height: "16", viewBox: "0 0 16 16", fill: "none", "aria-hidden": "true", children: _jsx("path", { d: "M4 6l4 4 4-4", stroke: "currentColor", strokeWidth: "1.5", strokeLinecap: "round", strokeLinejoin: "round" }) }) })] }), isOpen && (_jsxs(Div, { textSize: "sm", className: "text-[var(--appkit-color-text-muted)]", padding: "b-md", children: [faq.tags && faq.tags.length > 0 && (_jsx(Row, { wrap: true, gap: "sm", className: "mb-3", children: faq.tags.map((tag) => (_jsx(Span, { className: "bg-[var(--appkit-color-surface)] py-[0.25rem] text-[var(--appkit-color-text-muted)]", rounded: "md", padding: "x-xs", size: "xs", children: tag }, tag))) })), faq.answer.format === "html" ? (_jsx(RichText, { html: faq.answer.text, className: "prose-sm" })) : (_jsx(Text, { className: "whitespace-pre-line", children: faq.answer.text })), _jsx(Row, { justify: "end", className: "mt-3", children: _jsx(RecordOwnerQuickActions, { resource: "FAQ", recordId: faq.id, placement: "detail", recordLabel: faq.question }) }), renderExpandedFooter?.(faq)] }))] }));
 }
 export function FAQAccordion({ faqs, className = "", renderExpandedFooter, labels, }) {
     const [openId, setOpenId] = useState(null);

package/dist/features/faq/components/FAQCategorySidebar.js

@@ -3,9 +3,9 @@ import { Card, Div, Heading, Row, Span, Text, TextLink } from "../../../ui/index
 import { ROUTES } from "../../../next/routing/route-map.js";
 export function FAQCategorySidebar({ selectedCategory, onCategorySelect, categoryCounts, categories, allFaqsHref = String(ROUTES.PUBLIC.FAQS), categoryHref, contactHref, labels, }) {
     const totalCount = Object.values(categoryCounts).reduce((sum, count) => sum + count, 0);
-    return (_jsxs(Card, { variant: "outlined", padding: "lg", children: [_jsx(Heading, { level: 2, className: "mb-6", size: "lg", weight: "semibold", children: labels?.title ?? "Categories" }), _jsx(TextLink, { rounded: "lg", href: allFaqsHref, onClick: () => onCategorySelect?.("all"), className: `mb-3 block w-full p-[var(--appkit-space-4)] text-left transition-colors ${selectedCategory === "all" ? "bg-primary/10 text-[var(--appkit-color-text)]" : "text-[var(--appkit-color-text-muted)] hover:bg-[var(--appkit-color-surface)] text-[var(--appkit-color-text-muted)] dark:hover:bg-slate-700"}`, children: _jsxs(Row, { justify: "between", children: [_jsxs(Row, { gap: "3", children: [_jsx(Span, { size: "2xl", children: "FAQ" }), _jsx(Span, { size: "sm", weight: "medium", children: labels?.allFaqs ?? "All FAQs" })] }), _jsx(Span, { size: "xs", color: "muted", children: totalCount })] }) }), _jsx(Div, { border: "default", className: "mt-4 border-t", padding: "t-md", children: categories.map((category) => {
+    return (_jsxs(Card, { variant: "outlined", padding: "lg", children: [_jsx(Heading, { level: 2, className: "mb-6", size: "lg", weight: "semibold", children: labels?.title ?? "Categories" }), _jsx(TextLink, { rounded: "lg", href: allFaqsHref, onClick: () => onCategorySelect?.("all"), className: `mb-3 block w-full p-[var(--appkit-space-4)] text-left transition-colors ${selectedCategory === "all" ? "bg-primary/10 text-[var(--appkit-color-text)]" : "hover:bg-[var(--appkit-color-surface)] text-[var(--appkit-color-text-muted)] dark:hover:bg-slate-700"}`, children: _jsxs(Row, { justify: "between", children: [_jsxs(Row, { gap: "3", children: [_jsx(Span, { size: "2xl", children: "FAQ" }), _jsx(Span, { size: "sm", weight: "medium", children: labels?.allFaqs ?? "All FAQs" })] }), _jsx(Span, { size: "xs", color: "muted", children: totalCount })] }) }), _jsx(Div, { border: "default", className: "mt-4 border-t", padding: "t-md", children: categories.map((category) => {
                     const isSelected = selectedCategory === category.key;
                     const count = categoryCounts[category.key] || 0;
-                    return (_jsxs(TextLink, { rounded: "lg", href: categoryHref(category.key), onClick: () => onCategorySelect?.(category.key), className: `mb-3 block w-full p-[var(--appkit-space-4)] text-left transition-colors ${isSelected ? "bg-primary/10 text-[var(--appkit-color-text)]" : "text-[var(--appkit-color-text-muted)] hover:bg-[var(--appkit-color-surface)] text-[var(--appkit-color-text-muted)] dark:hover:bg-slate-700"}`, children: [_jsxs(Row, { justify: "between", className: "mb-1", children: [_jsxs(Row, { gap: "3", children: [category.icon ? (_jsx(Span, { size: "2xl", children: category.icon })) : null, _jsx(Span, { size: "sm", children: category.label })] }), _jsx(Span, { size: "xs", color: "muted", children: count })] }), isSelected && category.description ? (_jsx(Text, { className: "ml-11", color: "muted", size: "xs", children: category.description })) : null] }, category.key));
+                    return (_jsxs(TextLink, { rounded: "lg", href: categoryHref(category.key), onClick: () => onCategorySelect?.(category.key), className: `mb-3 block w-full p-[var(--appkit-space-4)] text-left transition-colors ${isSelected ? "bg-primary/10 text-[var(--appkit-color-text)]" : "hover:bg-[var(--appkit-color-surface)] text-[var(--appkit-color-text-muted)] dark:hover:bg-slate-700"}`, children: [_jsxs(Row, { justify: "between", className: "mb-1", children: [_jsxs(Row, { gap: "3", children: [category.icon ? (_jsx(Span, { size: "2xl", children: category.icon })) : null, _jsx(Span, { size: "sm", children: category.label })] }), _jsx(Span, { size: "xs", color: "muted", children: count })] }), isSelected && category.description ? (_jsx(Text, { className: "ml-11", color: "muted", size: "xs", children: category.description })) : null] }, category.key));
                 }) }), contactHref ? (_jsxs(Div, { border: "default", className: "border-t", padding: "t-lg", children: [_jsx(Text, { className: "mb-3", color: "muted", size: "sm", children: labels?.stillHaveQuestions ?? "Still have questions?" }), _jsx(TextLink, { rounded: "lg", href: contactHref, className: "block bg-primary p-[1rem] text-center text-white transition-colors hover:bg-primary/90", weight: "medium", children: labels?.contactSupport ?? "Contact Support" })] })) : null] }));
 }

package/dist/features/faq/components/FAQHelpfulButtons.js

@@ -43,10 +43,10 @@ export function FAQHelpfulButtons({ faqId, initialHelpful, initialNotHelpful, on
                     : (labels?.wasThisHelpful ?? "Was this helpful?") }), _jsxs(Row, { gap: "3", children: [_jsxs(Button, { variant: "ghost", onClick: () => handleVote(true), disabled: isPending || userVote !== null, className: `flex-1 gap-[var(--appkit-space-2)] rounded-lg p-[var(--appkit-space-4)] transition-all ${userVote === "helpful"
                             ? "bg-success-solid text-success-on-solid"
                             : userVote
-                                ? "cursor-not-allowed bg-zinc-200 text-[var(--appkit-color-text-muted)] opacity-50 dark:bg-slate-600 text-[var(--appkit-color-text-muted)]"
-                                : "bg-[var(--appkit-color-surface)] hover:bg-success-surface bg-[var(--appkit-color-surface-elevated)] text-[var(--appkit-color-text)]"}`, children: [_jsx(Span, { size: "sm", children: labels?.yes ?? "Yes" }), _jsxs(Span, { size: "sm", color: "muted", children: ["(", helpful, ")"] })] }), _jsxs(Button, { variant: "ghost", onClick: () => handleVote(false), disabled: isPending || userVote !== null, className: `flex-1 gap-[var(--appkit-space-2)] rounded-lg p-[var(--appkit-space-4)] transition-all ${userVote === "not-helpful"
+                                ? "cursor-not-allowed bg-zinc-200 opacity-50 dark:bg-slate-600 text-[var(--appkit-color-text-muted)]"
+                                : "hover:bg-success-surface bg-[var(--appkit-color-surface-elevated)] text-[var(--appkit-color-text)]"}`, children: [_jsx(Span, { size: "sm", children: labels?.yes ?? "Yes" }), _jsxs(Span, { size: "sm", color: "muted", children: ["(", helpful, ")"] })] }), _jsxs(Button, { variant: "ghost", onClick: () => handleVote(false), disabled: isPending || userVote !== null, className: `flex-1 gap-[var(--appkit-space-2)] rounded-lg p-[var(--appkit-space-4)] transition-all ${userVote === "not-helpful"
                             ? "bg-error-solid text-error-on-solid"
                             : userVote
-                                ? "cursor-not-allowed bg-zinc-200 text-[var(--appkit-color-text-muted)] opacity-50 dark:bg-slate-600 text-[var(--appkit-color-text-muted)]"
-                                : "bg-[var(--appkit-color-surface)] hover:bg-error-surface bg-[var(--appkit-color-surface-elevated)] text-[var(--appkit-color-text)]"}`, children: [_jsx(Span, { size: "sm", children: labels?.no ?? "No" }), _jsxs(Span, { size: "sm", color: "muted", children: ["(", notHelpful, ")"] })] })] })] }));
+                                ? "cursor-not-allowed bg-zinc-200 opacity-50 dark:bg-slate-600 text-[var(--appkit-color-text-muted)]"
+                                : "hover:bg-error-surface bg-[var(--appkit-color-surface-elevated)] text-[var(--appkit-color-text)]"}`, children: [_jsx(Span, { size: "sm", children: labels?.no ?? "No" }), _jsxs(Span, { size: "sm", color: "muted", children: ["(", notHelpful, ")"] })] })] })] }));
 }

package/dist/features/faq/components/RelatedFAQs.js

@@ -4,5 +4,5 @@ export function RelatedFAQs({ relatedFAQs, hrefForFaq, labels, }) {
     if (!relatedFAQs || relatedFAQs.length === 0) {
         return null;
     }
-    return (_jsxs(Card, { variant: "outlined", padding: "lg", children: [_jsx(Heading, { level: 3, className: "mb-4", size: "lg", weight: "semibold", children: labels?.title ?? "Related Questions" }), _jsx(Stack, { gap: "none", className: "divide-y divide-[var(--appkit-color-border)]", children: relatedFAQs.map((faq) => (_jsx(TextLink, { href: hrefForFaq ? hrefForFaq(faq) : `/faqs#${faq.id}`, className: "group block p-[1rem] transition-colors hover:bg-[var(--appkit-color-surface-elevated)]", children: _jsxs(Row, { align: "start", gap: "3", children: [_jsx("svg", { className: "mt-0.5 h-5 w-5 flex-shrink-0 text-[var(--appkit-color-text-muted)]", fill: "none", stroke: "currentColor", viewBox: "0 0 24 24", children: _jsx("path", { strokeLinecap: "round", strokeLinejoin: "round", strokeWidth: 2, d: "M8.228 9c.549-1.165 2.03-2 3.772-2 2.21 0 4 1.343 4 3 0 1.4-1.278 2.575-3.006 2.907-.542.104-.994.54-.994 1.093m0 3h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" }) }), _jsx(Text, { className: "transition-colors group-hover:text-primary", color: "primary", size: "sm", children: faq.question }), _jsx("svg", { className: "ml-auto mt-0.5 h-4 w-4 flex-shrink-0 pointer-events-none text-[var(--appkit-color-text-muted)] opacity-0 transition-opacity group-hover:opacity-100 text-[var(--appkit-color-text-muted)]", fill: "none", stroke: "currentColor", viewBox: "0 0 24 24", children: _jsx("path", { strokeLinecap: "round", strokeLinejoin: "round", strokeWidth: 2, d: "M9 5l7 7-7 7" }) })] }) }, faq.id))) })] }));
+    return (_jsxs(Card, { variant: "outlined", padding: "lg", children: [_jsx(Heading, { level: 3, className: "mb-4", size: "lg", weight: "semibold", children: labels?.title ?? "Related Questions" }), _jsx(Stack, { gap: "none", className: "divide-y divide-[var(--appkit-color-border)]", children: relatedFAQs.map((faq) => (_jsx(TextLink, { href: hrefForFaq ? hrefForFaq(faq) : `/faqs#${faq.id}`, className: "group block p-[1rem] transition-colors hover:bg-[var(--appkit-color-surface-elevated)]", children: _jsxs(Row, { align: "start", gap: "3", children: [_jsx("svg", { className: "mt-0.5 h-5 w-5 flex-shrink-0 text-[var(--appkit-color-text-muted)]", fill: "none", stroke: "currentColor", viewBox: "0 0 24 24", children: _jsx("path", { strokeLinecap: "round", strokeLinejoin: "round", strokeWidth: 2, d: "M8.228 9c.549-1.165 2.03-2 3.772-2 2.21 0 4 1.343 4 3 0 1.4-1.278 2.575-3.006 2.907-.542.104-.994.54-.994 1.093m0 3h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" }) }), _jsx(Text, { className: "transition-colors group-hover:text-primary", color: "primary", size: "sm", children: faq.question }), _jsx("svg", { className: "ml-auto mt-0.5 h-4 w-4 flex-shrink-0 pointer-events-none opacity-0 transition-opacity group-hover:opacity-100 text-[var(--appkit-color-text-muted)]", fill: "none", stroke: "currentColor", viewBox: "0 0 24 24", children: _jsx("path", { strokeLinecap: "round", strokeLinejoin: "round", strokeWidth: 2, d: "M9 5l7 7-7 7" }) })] }) }, faq.id))) })] }));
 }

package/dist/features/filters/FilterFacetSection.js

@@ -77,7 +77,7 @@ export function FilterFacetSection({ title, options, selected, onChange, selecti
     if (displayAs === "dropdown") {
         return (_jsxs(Div, { ref: dropdownRef, className: cn("relative inline-block", className), children: [_jsxs(Button, { type: "button", onClick: () => setDropdownOpen((o) => !o), variant: "ghost", className: cn("inline-flex items-center gap-[var(--appkit-space-1-5)] rounded-full border px-[var(--appkit-space-3)] py-[var(--appkit-space-1-5)] text-[length:var(--appkit-text-sm)] font-medium transition-colors", hasValue
                         ? CLS_OPTION_SELECTED
-                        : " bg-[var(--appkit-color-surface)] hover:border-zinc-400 border-[var(--appkit-color-border)] bg-[var(--appkit-color-surface)] text-[var(--appkit-color-text-muted)] hover:border-[var(--appkit-color-border)]"), children: [title, hasValue && (_jsx(Span, { weight: "bold", className: CLS_OPTION_DOT, children: selected.length })), _jsx("svg", { className: cn("h-3.5 w-3.5 text-zinc-400 transition-transform", dropdownOpen ? "rotate-180" : ""), fill: "none", viewBox: "0 0 24 24", stroke: "currentColor", strokeWidth: 2, "aria-hidden": "true", children: _jsx("path", { strokeLinecap: "round", strokeLinejoin: "round", d: "M19 9l-7 7-7-7" }) })] }), dropdownOpen && (_jsxs(Div, { className: "absolute left-0 top-full z-[var(--appkit-z-dropdown,50)] mt-1 min-w-[180px] max-w-[260px]", surface: "default", rounded: "xl", shadow: "lg", border: "default", children: [searchable && (_jsx(Div, { border: "subtle", className: "border-b", padding: "xs", children: _jsx(Input, { type: "search", placeholder: "Search\u2026", value: search, onChange: (e) => handleSearch(e.target.value), className: "w-full rounded-md border px-[var(--appkit-space-2)] py-[var(--appkit-space-1)] text-[length:var(--appkit-text-xs)] focus:outline-none border-[var(--appkit-color-border)] bg-[var(--appkit-color-surface-input)] text-[var(--appkit-color-text)]" }) })), _jsxs(Div, { className: `max-h-56 ${__O.yAuto}`, padding: "y-2xs", children: [filtered.map((option) => {
+                        : "hover:border-zinc-400 border-[var(--appkit-color-border)] bg-[var(--appkit-color-surface)] text-[var(--appkit-color-text-muted)] hover:border-[var(--appkit-color-border)]"), children: [title, hasValue && (_jsx(Span, { weight: "bold", className: CLS_OPTION_DOT, children: selected.length })), _jsx("svg", { className: cn("h-3.5 w-3.5 text-zinc-400 transition-transform", dropdownOpen ? "rotate-180" : ""), fill: "none", viewBox: "0 0 24 24", stroke: "currentColor", strokeWidth: 2, "aria-hidden": "true", children: _jsx("path", { strokeLinecap: "round", strokeLinejoin: "round", d: "M19 9l-7 7-7-7" }) })] }), dropdownOpen && (_jsxs(Div, { className: "absolute left-0 top-full z-[var(--appkit-z-dropdown,50)] mt-1 min-w-[180px] max-w-[260px]", surface: "default", rounded: "xl", shadow: "lg", border: "default", children: [searchable && (_jsx(Div, { border: "subtle", className: "border-b", padding: "xs", children: _jsx(Input, { type: "search", placeholder: "Search\u2026", value: search, onChange: (e) => handleSearch(e.target.value), className: "w-full rounded-md border px-[var(--appkit-space-2)] py-[var(--appkit-space-1)] text-[length:var(--appkit-text-xs)] focus:outline-none border-[var(--appkit-color-border)] bg-[var(--appkit-color-surface-input)] text-[var(--appkit-color-text)]" }) })), _jsxs(Div, { className: `max-h-56 ${__O.yAuto}`, padding: "y-2xs", children: [filtered.map((option) => {
                                     const isSelected = selected.includes(option.value);
                                     return (_jsxs(Row, { gap: "xs", className: "cursor-pointer py-[0.375rem] hover:bg-[var(--appkit-color-bg)] mx-1", padding: "x-sm", rounded: "lg", onClick: () => toggle(option.value), children: [_jsx(Checkbox, { bare: true, type: selectionMode === "single" ? "radio" : "checkbox", checked: isSelected, onChange: () => toggle(option.value), "aria-label": option.label, className: "h-3.5 w-3.5 flex-shrink-0 cursor-pointer rounded text-primary-600 border-[var(--appkit-color-border)] dark:text-secondary-500" }), _jsx(Span, { size: "xs", className: "flex-1 truncate", color: "muted", children: option.label }), option.count !== undefined && (_jsx(Span, { className: "flex-shrink-0 text-[10px] tabular-nums", color: "faint", children: option.count }))] }, option.value));
                                 }), filtered.length === 0 && (_jsx(Text, { paddingY: "xs", paddingX: "x-sm", color: "faint", size: "xs", children: "No results" }))] }), hasValue && (_jsx(Div, { border: "subtle", className: "border-t p-[0.25rem]", children: _jsx(Button, { type: "button", variant: "ghost", size: "sm", className: CLS_CLEAR_BTN, onClick: () => { onChange([]); onClear?.(); setDropdownOpen(false); }, children: "Clear" }) }))] }))] }));

package/dist/features/filters/SwitchFilter.js

@@ -14,5 +14,5 @@ export function SwitchFilter({ title, label, checked, onChange, defaultCollapsed
         else
             setInternalCollapsed((c) => !c);
     };
-    return (_jsxs(Div, { role: "group", "aria-labelledby": `sf-${title}`, className: cn("p-[var(--appkit-space-4)] border-b border-[var(--appkit-color-border)] last:border-b-0", className), children: [_jsxs(Row, { gap: "sm", children: [_jsxs(Button, { type: "button", id: `sf-${title}`, onClick: handleToggle, variant: "ghost", size: "sm", justify: "between", className: "flex-1 text-[0.875rem] font-[600] text-[var(--appkit-color-text)] py-[0.25rem] hover:opacity-80 transition-opacity", "aria-expanded": !isCollapsed, children: [_jsx(Text, { size: "sm", weight: "semibold", color: "primary", children: title }), _jsx("svg", { className: cn("w-4 h-4 shrink-0 text-[var(--appkit-color-text-muted)] transition-transform duration-200", isCollapsed ? "" : "rotate-180"), fill: "none", viewBox: "0 0 24 24", stroke: "currentColor", strokeWidth: 2, "aria-hidden": "true", children: _jsx("path", { strokeLinecap: "round", strokeLinejoin: "round", d: "M19 9l-7 7-7-7" }) })] }), checked && onClear && (_jsx(Button, { type: "button", onClick: onClear, variant: "ghost", size: "sm", className: CLS_CLEAR_BTN, "aria-label": "Clear", children: _jsx("svg", { className: "w-3 h-3 shrink-0", fill: "none", viewBox: "0 0 24 24", stroke: "currentColor", strokeWidth: 2.5, "aria-hidden": "true", children: _jsx("path", { strokeLinecap: "round", strokeLinejoin: "round", d: "M6 18L18 6M6 6l12 12" }) }) }))] }), !isCollapsed && (_jsxs(Row, { className: "mt-3", align: "center", justify: "between", gap: "3", children: [_jsx(Span, { size: "sm", color: "muted", children: label }), _jsx(Toggle, { checked: checked, onChange: onChange, size: "sm" })] }))] }));
+    return (_jsxs(Div, { role: "group", "aria-labelledby": `sf-${title}`, className: cn("p-[var(--appkit-space-4)] border-b border-[var(--appkit-color-border)] last:border-b-0", className), children: [_jsxs(Row, { gap: "sm", children: [_jsxs(Button, { type: "button", id: `sf-${title}`, onClick: handleToggle, variant: "ghost", size: "sm", justify: "between", className: "flex-1 text-[0.875rem] font-[600] text-[var(--appkit-color-text)] py-[0.25rem] hover:opacity-80 transition-opacity", "aria-expanded": !isCollapsed, children: [_jsx(Text, { size: "sm", weight: "semibold", color: "primary", children: title }), _jsx("svg", { className: cn("w-4 h-4 shrink-0 text-[var(--appkit-color-text-muted)] transition-transform duration-200", isCollapsed ? "" : "rotate-180"), fill: "none", viewBox: "0 0 24 24", stroke: "currentColor", strokeWidth: 2, "aria-hidden": "true", children: _jsx("path", { strokeLinecap: "round", strokeLinejoin: "round", d: "M19 9l-7 7-7-7" }) })] }), checked && onClear && (_jsx(Button, { type: "button", onClick: onClear, variant: "ghost", size: "sm", className: CLS_CLEAR_BTN, "aria-label": "Clear", children: _jsx("svg", { className: "w-3 h-3 shrink-0", fill: "none", viewBox: "0 0 24 24", stroke: "currentColor", strokeWidth: 2.5, "aria-hidden": "true", children: _jsx("path", { strokeLinecap: "round", strokeLinejoin: "round", d: "M6 18L18 6M6 6l12 12" }) }) }))] }), !isCollapsed && (_jsxs(Row, { className: "mt-3", align: "center", justify: "between", gap: "3", children: [_jsx(Span, { size: "sm", color: "muted", children: label }), _jsx(Toggle, { checked: checked, onChange: onChange, size: "sm", "aria-label": label })] }))] }));
 }

package/dist/features/gateway-events/repository/gateway-events.repository.d.ts

@@ -0,0 +1,117 @@
+import type { DocumentReference } from "firebase-admin/firestore";
+import type { FirebaseSieveFields, FirebaseSieveResult, SieveModel } from "../../../providers/db-firebase";
+import { BaseRepository } from "../../../providers/db-firebase";
+import { type GatewayEventDocument, type GatewayEventKind, type GatewayEventStatus } from "../schemas/firestore";
+export interface GatewayEventClaimInput {
+    gateway: string;
+    rawEvent: string;
+    kind: GatewayEventKind;
+    bodySha256: string;
+    providerEventId?: string;
+    gatewayOrderId?: string;
+    gatewayPaymentId?: string;
+    amount?: number;
+    payload?: GatewayEventDocument["payload"];
+    payloadTruncated?: boolean;
+    /** Injectable so a job's `ctx.now` drives the lease rather than wall clock. */
+    now?: Date;
+}
+export type GatewayEventClaimResult = {
+    claimed: true;
+    id: string;
+    doc: GatewayEventDocument;
+} | {
+    claimed: false;
+    id: string;
+};
+export interface GatewayEventSettleInput {
+    status: GatewayEventStatus;
+    orderIds?: string[];
+    lastError?: string;
+    terminal?: boolean;
+    now?: Date;
+}
+export declare class GatewayEventsRepository extends BaseRepository<GatewayEventDocument> {
+    /**
+     * 🛑 Every date field carries `parseValue: parseSieveDateValue`, and it is not
+     * optional: these are stored Firestore Timestamps, and sievejs' default
+     * `convertValue()` only coerces `"true"`/`"false"`/numeric strings. An ISO
+     * string therefore reaches the adapter unchanged and becomes
+     * `.where("receivedAt", ">=", "<iso-string>")` — a type mismatch against a
+     * Timestamp, which matches **zero documents with no error at all**
+     * (Root Cause #47). `audit-sieve-date-fields` blocks the omission.
+     */
+    static readonly SIEVE_FIELDS: FirebaseSieveFields;
+    constructor();
+    /**
+     * Persist-and-claim in one write. Returns `claimed: false` for a duplicate.
+     *
+     * 🛑 THROWS on any write failure that is not a duplicate — see
+     * `isAlreadyExists`. The caller must translate that into a 503 so the gateway
+     * redelivers; swallowing it is how an event is lost.
+     */
+    claim(input: GatewayEventClaimInput): Promise<GatewayEventClaimResult>;
+    /** Flip a claimed row to its outcome. Never throws — see the docstring. */
+    settle(id: string, input: GatewayEventSettleInput): Promise<void>;
+    /**
+     * R1's query: rows claimed but never settled, whose lease has lapsed.
+     *
+     * 🛑 `status` is an `in` equality and `leaseExpiresAt` the single inequality,
+     * which is the only shape Firestore will serve without demanding the
+     * inequality field lead the `orderBy` (Root Cause #59). Ordered by
+     * `leaseExpiresAt` for exactly that reason — not by `receivedAt`, which would
+     * need an index in an order nobody declares.
+     */
+    listStuck(now: Date, limit?: number): Promise<GatewayEventDocument[]>;
+    /**
+     * Make the NEXT delivery of this event be accepted instead of acked.
+     *
+     * ## 🛑 IT DOES NOT REPROCESS ANYTHING, AND THE NAME SAYS SO
+     *
+     * There is no way to replay a gateway event from here, deliberately. R1's own
+     * header gives the reason: re-dispatching from a job or an admin button would
+     * mean duplicating the webhook route's entire switch — and its RTDB
+     * signalling — in a second place, which is Root Cause #75 on the dispatch
+     * axis. The webhook route is the only thing that knows how to handle an event.
+     *
+     * So this reopens the DOOR and nothing more. The operator still has to press
+     * Resend in the gateway dashboard (or wait for the gateway's own retry); this
+     * is what stops the inbox from refusing that redelivery as a duplicate.
+     *
+     * Anything calling this must tell the operator that second step is theirs. A
+     * button labelled "Reprocess" that only did this would be the worst kind of
+     * half-truth — it would look like the work had been done.
+     *
+     * ## Why these four fields, read off `resolveDuplicateDelivery`'s table
+     *
+     * That function decides ack-vs-redispatch, and three of its branches would
+     * otherwise swallow the redelivery:
+     *
+     *   · `processed` / `ignored` / `conflict` → always ack. Hence `status` is
+     *     reset to `failed`, the one non-terminal state that redispatches.
+     *   · `failed` + `terminal: true` → ack. Hence `terminal: false`.
+     *   · lapsed lease but `attempts >= GATEWAY_EVENT_MAX_ATTEMPTS` → ack. Hence
+     *     `attempts: 0`.
+     *
+     * And the lease is set to `now`, i.e. already expired, because the
+     * received/processing branch is decided by the LEASE rather than the status —
+     * a live lease means "another worker has this" and must keep acking.
+     *
+     * `lastError` records that a human did this, so the row does not read as a
+     * fresh transient failure to whoever looks next.
+     */
+    reopenForRedelivery(id: string, actorUid: string, now?: Date): Promise<void>;
+    /** Take over a lapsed lease and count the attempt. */
+    renewLease(id: string, attempts: number, now: Date): Promise<void>;
+    /** Every event for one gateway order — the reconciliation join. */
+    findByGatewayOrderId(gatewayOrderId: string): Promise<GatewayEventDocument[]>;
+    /**
+     * Retention: refs for rows past `expiresAt`, for the caller's batch delete.
+     * Mirrors `sessionRepository.getExpiredRefs` so `dailyDataCleanup` composes
+     * it the same way it composes sessions and tokens.
+     */
+    getExpiredRefs(now: Date, limit?: number): Promise<DocumentReference[]>;
+    list(model: SieveModel): Promise<FirebaseSieveResult<GatewayEventDocument>>;
+}
+/** Lazy singleton — avoids cold-start admin SDK init when nothing is ingesting. */
+export declare function gatewayEventsRepository(): GatewayEventsRepository;