@mohasinac/appkit 4.58.0 → 4.60.0

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

@@ -40,7 +40,7 @@ import type { BaseDocument } from "../../../_internal/shared/types/base-document
  * error at every exhaustive read rather than an unlabelled row. The admin
  * answer to "why do I have 53 points" is this field.
  */
-export declare const POINTS_ENTRY_KIND_VALUES: readonly ["shipping_saving", "redemption", "redemption_reversal", "admin_adjustment"];
+export declare const POINTS_ENTRY_KIND_VALUES: readonly ["shipping_saving", "purchase_earn", "redemption", "redemption_reversal", "admin_adjustment"];
 export type PointsEntryKind = (typeof POINTS_ENTRY_KIND_VALUES)[number];
 export interface PointsLedgerEntry extends BaseDocument {
     /** Auth UID of the buyer. The ledger is keyed on the person, not the order. */
@@ -70,6 +70,57 @@ export interface PointsLedgerEntry extends BaseDocument {
     adminReason?: string;
     /** Who made an `admin_adjustment`. */
     actorUid?: string;
+    /**
+     * When this batch of points stops being spendable.
+     *
+     * ## 🛑 PER ENTRY, three months, FIFO on redemption
+     *
+     * Decision 4. Per-entry rather than a single per-user expiry date because
+     * points arrive in batches and each batch has its own clock — a credit earned
+     * today must not be shortened by one earned three months ago, and a single
+     * date can only express one of those.
+     *
+     * Redemption consumes OLDEST-FIRST so a buyer never loses points they could
+     * have spent. The alternative (newest-first) silently maximises expiry, which
+     * is the house always winning by a mechanism nobody announced.
+     *
+     * Absent on a `redemption`, a `redemption_reversal` and usually on an
+     * `admin_adjustment`: a spend has nothing to expire, and a reversal restores
+     * points whose original clock has already been consumed — giving it a fresh
+     * three months would be a quiet extension nobody granted.
+     *
+     * 🛑 Absent also means NEVER EXPIRES, which is the right default for every
+     * entry written before this field existed. Treating absence as "expired" would
+     * retroactively void live balances; treating it as "never" leaves a bounded,
+     * knowable residue that the reconciliation job can report.
+     */
+    expiresAt?: Date;
+    /**
+     * Points consumed out of this credit by later redemptions.
+     *
+     * 🛑 FIFO needs to know how much of each batch is left, and an append-only
+     * ledger cannot answer that from the sum alone: two credits of 50 and a spend
+     * of 60 sum to 40, but WHICH 40 is left decides what expires when. So a
+     * redemption writes its negative entry AND increments this counter on the
+     * batches it drew from.
+     *
+     * That makes this the one mutable field on an otherwise append-only row, and
+     * it is a deliberate, narrow exception: the alternative is deriving
+     * consumption by replaying every entry in order on every read, which is
+     * O(ledger) per balance check and gets slower forever.
+     */
+    consumed?: number;
+    /**
+     * On a `redemption` only: the credit batches this spend drew from, in the
+     * order it drew from them.
+     *
+     * 🛑 Recorded ON the spend rather than derived later. A reversal needs to know
+     * what to give back, and by then those batches may themselves have expired —
+     * "return it where it came from" is only answerable if the spend wrote it
+     * down. Deriving it afterwards would mean replaying the whole ledger and
+     * guessing at a FIFO order that may since have changed.
+     */
+    drawnFrom?: string[];
 }
 /**
  * The ledger's own invariant, stated once so every writer can be checked
@@ -96,6 +147,8 @@ export declare const POINTS_FIELDS: {
     readonly AMOUNT: "amount";
     readonly ORDER_ID: "orderId";
     readonly CREATED_AT: "createdAt";
+    readonly EXPIRES_AT: "expiresAt";
+    readonly CONSUMED: "consumed";
 };
 /**
  * 🛑 Points cannot pay for the whole order, and this is the cap that enforces
@@ -116,3 +169,57 @@ export declare const POINTS_MAX_REDEMPTION_PERCENT = 50;
  * credited.
  */
 export declare function maxRedeemablePoints(orderTotal: number, balance: number): number;
+/**
+ * How long a credit stays spendable. Decision 4: three months from issue.
+ *
+ * 🛑 A tighter bound than inactivity-based expiry on purpose. The liability
+ * here is unbounded without one (D49: there is no expiry at all today), and
+ * "three months from this batch" is a figure a buyer can check against their
+ * own ledger — whereas "twelve months since you last did anything" is a date
+ * that moves for reasons they cannot see.
+ */
+export declare const POINTS_EXPIRY_MONTHS = 3;
+/**
+ * Percentage of an order's post-discount GOODS value earned as points.
+ *
+ * 🛑 GOODS, never the order total. "5% of what you paid" read literally
+ * includes shipping and the platform fee — so we would issue points against
+ * postage handed to a courier. And it excludes the points TENDER itself, or
+ * points breed points: pay ₹100 with points, earn 5, pay with those, earn
+ * again. It converges, but it leaks value and is indefensible on a balance
+ * sheet.
+ */
+export declare const POINTS_EARN_PERCENT = 5;
+/**
+ * The largest single manual adjustment an admin may make, in points (= ₹).
+ *
+ * 🛑 The realistic failure here is a TYPO, not malice. `isPointsEntryWellFormed`
+ * checks sign and reason but says nothing about magnitude, so `50000` where
+ * `500` was meant passes every check and mints ₹50,000 of spendable liability
+ * in one click. Bounded on the ABSOLUTE value so the debit direction is guarded
+ * too — a mistyped debit wipes a balance the buyer earned, and the only undo is
+ * another adjustment.
+ *
+ * A genuinely larger correction is several deliberate adjustments, each with
+ * its own reason and its own `adminAuditLog` row. That is the right amount of
+ * friction for a number this size.
+ */
+export declare const POINTS_ADJUSTMENT_MAX = 5000;
+/**
+ * Minimum length of an adjustment's `adminReason`.
+ *
+ * Deliberately the same 10 characters as `paymentCaseResolveFormSchema`, so an
+ * operator meets ONE rule across the admin surfaces rather than two that differ
+ * for no reason. A length rather than mere presence because the reader is the
+ * next admin asking "why does this account have 53 points", and "fix" answers
+ * nothing.
+ */
+export declare const POINTS_ADJUSTMENT_REASON_MIN = 10;
+/**
+ * When does a batch of points issued now expire?
+ *
+ * A function rather than a constant offset because months are not a fixed
+ * number of days — `setMonth` handles the 31st-of-a-short-month case the way a
+ * human reading "three months" expects, which a `+ 90 * 86400000` does not.
+ */
+export declare function pointsExpiryFrom(issuedAt: Date): Date;

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

@@ -42,6 +42,29 @@
 export const POINTS_ENTRY_KIND_VALUES = [
     /** Shipping charged minus shipping actually spent, credited after dispatch. */
     "shipping_saving",
+    /**
+     * Earned on a COMPLETED purchase — the owner's rule, 2026-10-21.
+     *
+     * 🛑 There was NO earn kind before this. The four original values covered
+     * shipping savings, redemption, its reversal and an admin adjustment — so
+     * the programme could give points back and take them away but had no way to
+     * issue them for a purchase, which is the entire point of it.
+     *
+     * Awarded at COMPLETION, not at checkout: *"points only get issued on
+     * successful purchases after buyer put reviews, then only… they are also
+     * assigned if the user [raises] no issues after 7 days of delivery."* So
+     * completion has two triggers and they converge on one fact (`completedAt`),
+     * which is why the award must be keyed on something written once — see
+     * `pointsAwardedAt` on the order.
+     *
+     * 🛑 The STORE bears it (owner: *"so stores bear it"*), as a discount
+     * expense: *"the cost is like a sale discount for getting a repeat customer
+     * you get to pay few loss."* It is a deduction term in the payout, never a
+     * clawback — `payout-release` is `blockedBy: ["order-complete"]`, so the
+     * award is ALWAYS strictly before the payout is computed, by construction
+     * rather than by timing luck.
+     */
+    "purchase_earn",
     /** Spent against an order's total at checkout. Always negative. */
     "redemption",
     /** A redemption returned because the order it paid for was cancelled. */
@@ -65,6 +88,7 @@ export function isPointsEntryWellFormed(entry) {
             return entry.amount < 0;
         case "shipping_saving":
         case "redemption_reversal":
+        case "purchase_earn":
             return entry.amount > 0;
         case "admin_adjustment":
             return Boolean(entry.adminReason && entry.adminReason.trim().length >= 10);
@@ -86,6 +110,8 @@ export const POINTS_FIELDS = {
     AMOUNT: "amount",
     ORDER_ID: "orderId",
     CREATED_AT: "createdAt",
+    EXPIRES_AT: "expiresAt",
+    CONSUMED: "consumed",
 };
 /**
  * 🛑 Points cannot pay for the whole order, and this is the cap that enforces
@@ -114,3 +140,61 @@ export function maxRedeemablePoints(orderTotal, balance) {
     const cap = Math.floor((orderTotal * POINTS_MAX_REDEMPTION_PERCENT) / 100);
     return Math.max(0, Math.min(Math.floor(balance), cap));
 }
+/**
+ * How long a credit stays spendable. Decision 4: three months from issue.
+ *
+ * 🛑 A tighter bound than inactivity-based expiry on purpose. The liability
+ * here is unbounded without one (D49: there is no expiry at all today), and
+ * "three months from this batch" is a figure a buyer can check against their
+ * own ledger — whereas "twelve months since you last did anything" is a date
+ * that moves for reasons they cannot see.
+ */
+export const POINTS_EXPIRY_MONTHS = 3;
+/**
+ * Percentage of an order's post-discount GOODS value earned as points.
+ *
+ * 🛑 GOODS, never the order total. "5% of what you paid" read literally
+ * includes shipping and the platform fee — so we would issue points against
+ * postage handed to a courier. And it excludes the points TENDER itself, or
+ * points breed points: pay ₹100 with points, earn 5, pay with those, earn
+ * again. It converges, but it leaks value and is indefensible on a balance
+ * sheet.
+ */
+export const POINTS_EARN_PERCENT = 5;
+/**
+ * The largest single manual adjustment an admin may make, in points (= ₹).
+ *
+ * 🛑 The realistic failure here is a TYPO, not malice. `isPointsEntryWellFormed`
+ * checks sign and reason but says nothing about magnitude, so `50000` where
+ * `500` was meant passes every check and mints ₹50,000 of spendable liability
+ * in one click. Bounded on the ABSOLUTE value so the debit direction is guarded
+ * too — a mistyped debit wipes a balance the buyer earned, and the only undo is
+ * another adjustment.
+ *
+ * A genuinely larger correction is several deliberate adjustments, each with
+ * its own reason and its own `adminAuditLog` row. That is the right amount of
+ * friction for a number this size.
+ */
+export const POINTS_ADJUSTMENT_MAX = 5000;
+/**
+ * Minimum length of an adjustment's `adminReason`.
+ *
+ * Deliberately the same 10 characters as `paymentCaseResolveFormSchema`, so an
+ * operator meets ONE rule across the admin surfaces rather than two that differ
+ * for no reason. A length rather than mere presence because the reader is the
+ * next admin asking "why does this account have 53 points", and "fix" answers
+ * nothing.
+ */
+export const POINTS_ADJUSTMENT_REASON_MIN = 10;
+/**
+ * When does a batch of points issued now expire?
+ *
+ * A function rather than a constant offset because months are not a fixed
+ * number of days — `setMonth` handles the 31st-of-a-short-month case the way a
+ * human reading "three months" expects, which a `+ 90 * 86400000` does not.
+ */
+export function pointsExpiryFrom(issuedAt) {
+    const out = new Date(issuedAt.getTime());
+    out.setMonth(out.getMonth() + POINTS_EXPIRY_MONTHS);
+    return out;
+}

package/dist/features/pre-orders/components/MarketplacePreorderCard.js

@@ -19,7 +19,7 @@ import { normalizeRichTextHtml } from "../../../utils/string.formatter.js";
 import { PreorderBadge } from "./PreorderCard.js";
 import { WishlistHeartButton } from "../../wishlist/components/WishlistHeartButton.js";
 import { CardStoreLine } from "../../products/components/CardStoreLine.js";
-import { ProductOwnerQuickActions } from "../../products/components/ProductOwnerQuickActions.js";
+import { RecordOwnerQuickActions } from "../../admin/components/RecordOwnerQuickActions.js";
 const DEFAULT_LABELS = {
     preOrderBadge: "Pre-order",
     featuredBadge: "Featured",
@@ -80,7 +80,7 @@ export function MarketplacePreorderCard({ product, className = "", variant = "gr
     const ownerActions = renderOwnerActions
         ? renderOwnerActions()
         : product.id
-            ? (_jsx(ProductOwnerQuickActions, { productId: String(product.id), storeId: product.storeId ? String(product.storeId) : undefined, recordLabel: product.title, placement: "card" }))
+            ? (_jsx(RecordOwnerQuickActions, { resource: "PRODUCT", recordId: String(product.id), storeId: product.storeId ? String(product.storeId) : undefined, recordLabel: product.title, placement: "card" }))
             : null;
     if (!ownerActions)
         return card;
@@ -88,5 +88,5 @@ export function MarketplacePreorderCard({ product, className = "", variant = "gr
      * Sibling of the card, never a child — see the prop's docstring. `z-20`
      * clears this card's own overlays, which all sit at `z-10`.
      */
-    return (_jsxs(Div, { className: "relative h-full", children: [card, _jsx(Div, { className: "absolute right-2 bottom-2 z-20", children: ownerActions })] }));
+    return (_jsxs(Div, { className: "flex h-full flex-col", children: [card, _jsx(Div, { className: "flex justify-end px-[var(--appkit-space-3)] pb-[var(--appkit-space-3)]", children: ownerActions })] }));
 }

package/dist/features/pre-orders/components/PreOrderBadge.js

@@ -5,7 +5,7 @@ const STATUS_MAP = {
     pending: { label: "Pending", color: "bg-warning-surface text-warning" },
     confirmed: { label: "Confirmed", color: "bg-info-surface text-info" },
     ready: { label: "Ready", color: "bg-success-surface text-success" },
-    fulfilled: { label: "Fulfilled", color: "bg-[var(--appkit-color-surface)] bg-[var(--appkit-color-surface-elevated)] text-[var(--appkit-color-text-muted)]" },
+    fulfilled: { label: "Fulfilled", color: "bg-[var(--appkit-color-surface-elevated)] text-[var(--appkit-color-text-muted)]" },
     cancelled: { label: "Cancelled", color: "bg-error-surface text-error" },
 };
 export function PreOrderBadge({ status, className = "" }) {

package/dist/features/pre-orders/components/PreOrderDetailPageView.js

@@ -50,7 +50,7 @@ const PRODUCTION_STATUS_LABELS = {
     ready_to_ship: "Ready to Ship",
 };
 function PreOrderInfoSection({ title, productId, storeId, productionStatus, maxPerUser, deliveryDate, featured, freeShipping, condition, isCancellable, finalSale, category, categoryName, brand, brandSlug, productFeatures, features, descriptionHtml, safeSeller, storeHref, }) {
-    return (_jsxs(Stack, { gap: "md", children: [_jsxs(Div, { children: [_jsxs(Row, { gap: "xs", wrap: true, className: "mb-2", children: [_jsx(Span, { size: "xs", weight: "semibold", className: CLS_PREORDER_BADGE, children: "Pre-Order" }), productionStatus && (_jsx(Span, { size: "xs", weight: "medium", className: "inline-block", padding: "pill-sm", rounded: "full", surface: "subtle", color: "muted", children: PRODUCTION_STATUS_LABELS[productionStatus] ?? productionStatus })), maxPerUser !== null && (_jsxs(Span, { size: "xs", weight: "medium", className: CLS_STATUS_BADGE, children: ["Limit: ", maxPerUser, " per customer"] }))] }), productId && (_jsx(OwnerQuickActions, { resource: "PRODUCT", placement: "detail", recordLabel: title, storeId: storeId, editHref: String(ROUTES.STORE.PRODUCTS_EDIT(productId)) })), _jsx(Heading, { level: 1, className: "leading-snug", smSize: "2xl", color: "primary", size: "xl", weight: "bold", children: title })] }), deliveryDate && (_jsxs(Row, { color: "muted", textSize: "sm", align: "center", gap: "xs", children: [_jsx(Span, { children: "\uD83D\uDCC5" }), _jsx(Span, { children: "Estimated delivery:" }), _jsx(Span, { weight: "medium", children: deliveryDate.toLocaleDateString(undefined, { year: "numeric", month: "long" }) })] })), _jsx(ProductFeatureBadges, { featured: featured, freeShipping: freeShipping, condition: condition ?? undefined, returnable: isCancellable, finalSale: finalSale, labels: {
+    return (_jsxs(Stack, { gap: "md", children: [_jsxs(Div, { children: [_jsxs(Row, { gap: "xs", wrap: true, className: "mb-2", children: [_jsx(Span, { size: "xs", weight: "semibold", className: CLS_PREORDER_BADGE, children: "Pre-Order" }), productionStatus && (_jsx(Span, { size: "xs", weight: "medium", className: "inline-block", padding: "pill-sm", rounded: "full", surface: "subtle", color: "muted", children: PRODUCTION_STATUS_LABELS[productionStatus] ?? productionStatus })), maxPerUser !== null && (_jsxs(Span, { size: "xs", weight: "medium", className: CLS_STATUS_BADGE, children: ["Limit: ", maxPerUser, " per customer"] }))] }), _jsx(Heading, { level: 1, className: "leading-snug", smSize: "2xl", color: "primary", size: "xl", weight: "bold", children: title }), productId && (_jsx(OwnerQuickActions, { resource: "PRODUCT", placement: "detail", recordLabel: title, storeId: storeId, editHref: String(ROUTES.STORE.PRODUCTS_EDIT(productId)) }))] }), deliveryDate && (_jsxs(Row, { color: "muted", textSize: "sm", align: "center", gap: "xs", children: [_jsx(Span, { children: "\uD83D\uDCC5" }), _jsx(Span, { children: "Estimated delivery:" }), _jsx(Span, { weight: "medium", children: deliveryDate.toLocaleDateString(undefined, { year: "numeric", month: "long" }) })] })), _jsx(ProductFeatureBadges, { featured: featured, freeShipping: freeShipping, condition: condition ?? undefined, returnable: isCancellable, finalSale: finalSale, labels: {
                     featured: "Featured",
                     fasterDelivery: "Faster Delivery",
                     ratedSeller: "Rated Seller",

package/dist/features/price-index/components/PriceIndexToolView.d.ts

@@ -80,14 +80,24 @@ export interface PriceIndexToolResponse {
     minConfidentSamples: number;
 }
 /**
- * The competitor-crawl band for one leaf. Mirrors `PriceIndexMarketRow`.
+ * The asking-price band for one leaf. Mirrors `PriceIndexMarketRow`.
  *
- * Every field but `median` and `categoryId` is optional because the crawl
- * genuinely did not measure them everywhere, and an absent figure must render
- * as absent. See `price-bands.md`: "a band with `n=2` is not evidence".
+ * Every field but `median`, `categoryId` and `origin` is optional, because the
+ * two kinds of row carry genuinely different evidence and an absent figure
+ * must render as absent. See `price-bands.md`: "a band with `n=2` is not
+ * evidence".
+ *
+ * 🛑 `origin` decides what the card is ALLOWED to claim, and the two cases are
+ * not cosmetic variants of each other:
+ *
+ *   `computed`  a mode over dated sightings of THIS leaf. May be called "most
+ *               common" and, when `basedOnRecent`, "last 6 months".
+ *   `seeded`    the 2026-10 crawl's median for an entire GENERATION, frozen at
+ *               one date. May be called neither.
  */
 export interface PriceIndexMarketRowView {
     categoryId: string;
+    origin: "computed" | "seeded";
     median: number;
     p25?: number;
     p75?: number;
@@ -95,6 +105,15 @@ export interface PriceIndexMarketRowView {
     asOf?: string;
     soldOutShare?: number;
     source?: string;
+    /** `computed` only — the price sightings cluster on. */
+    mode?: number;
+    modeCount?: number;
+    low?: number;
+    high?: number;
+    /** `false` ⇒ the figures are all-time, not the last six months. */
+    basedOnRecent?: boolean;
+    windowDays?: number;
+    lastSeenAt?: string;
     inherited: boolean;
     viaCategoryId?: string;
     viaName?: string;

package/dist/features/price-index/components/PriceIndexToolView.js

@@ -79,9 +79,16 @@ function relativeDay(iso) {
     const months = Math.floor(days / 30);
     return months === 1 ? "1 month ago" : `${months} months ago`;
 }
-/** One figure with its label. Four of these, never one called "the price". */
-function Figure({ label, value }) {
-    return (_jsxs(Stack, { gap: "none", className: "min-w-0", children: [_jsx(Text, { size: "xs", color: "muted", transform: "uppercase", className: "tracking-wide", children: label }), _jsx(Text, { size: "lg", weight: "semibold", numeric: true, className: "tabular-nums", children: value })] }));
+/**
+ * One figure with its label. Four of these, never one called "the price".
+ *
+ * `dim` renders the figure at body size in muted ink. It is how a GENERATION
+ * band is demoted below a per-model one — the numbers stay readable, because a
+ * ballpark is better than nothing, but they stop looking like a measurement of
+ * the thing the card is headed by.
+ */
+function Figure({ label, value, dim }) {
+    return (_jsxs(Stack, { gap: "none", className: "min-w-0", children: [_jsx(Text, { size: "xs", color: "muted", transform: "uppercase", className: "tracking-wide", children: label }), _jsx(Text, { size: dim ? "base" : "lg", weight: dim ? "medium" : "semibold", ...(dim ? { color: "muted" } : {}), numeric: true, className: "tabular-nums", children: value })] }));
 }
 function LowConfidence({ sampleSize, threshold }) {
     return (_jsxs(Text, { size: "sm", color: "muted", children: ["Only ", sampleSize, " ", sampleSize === 1 ? "sale" : "sales", " recorded \u2014 not enough to publish a figure yet. We show a price once there are", " ", threshold, "."] }));
@@ -119,12 +126,59 @@ function BandCard({ band, threshold }) {
  * Burst DB" is true, "typical for Rage Longinus" is not.
  */
 function MarketCard({ market }) {
-    const hasRange = market.p25 !== undefined && market.p75 !== undefined;
     const soldOutPct = market.soldOutShare === undefined ? null : Math.round(market.soldOutShare * 100);
-    return (_jsxs(Stack, { gap: "sm", padding: "sm", rounded: "lg", border: "default", className: "min-w-0", children: [_jsxs(Row, { align: "center", justify: "between", gap: "sm", wrap: true, className: "min-w-0", children: [_jsx(Badge, { variant: "secondary", children: "Typical asking price" }), market.sampleSize !== undefined && (_jsxs(Text, { size: "xs", color: "muted", children: [market.sampleSize, " ", market.sampleSize === 1 ? "listing" : "listings"] }))] }), _jsxs(Row, { gap: "lg", wrap: true, className: "min-w-0", children: [hasRange && _jsx(Figure, { label: "Usual low", value: money(market.p25) }), _jsx(Figure, { label: "Typical ask", value: money(market.median) }), hasRange && _jsx(Figure, { label: "Usual high", value: money(market.p75) })] }), market.inherited && (_jsxs(Text, { size: "sm", color: "muted", children: ["Measured for", " ", _jsx(Span, { weight: "semibold", children: market.viaName ?? market.viaCategoryId }), " as a whole \u2014 the crawl priced the generation, not this exact item."] })), soldOutPct !== null && (_jsxs(Text, { size: "sm", color: "muted", children: ["These are asking prices from other shops, and about ", soldOutPct, "% of listings at this level are sold out \u2014 so an ask is not proof anything changed hands at it."] })), _jsxs(Text, { size: "xs", color: "muted", className: "min-w-0 break-words", children: [market.source ? `Source: ${market.source}. ` : "", "Tax-inclusive", market.asOf
+    /*
+     * 🛑 A SEEDED band is a generation median and a COMPUTED one is a mode over
+     * dated sightings of this exact leaf. They are rendered differently because
+     * they support different claims, not because one looks nicer — the single
+     * worst thing this card could do is print a generation's figure in the
+     * typography of a per-model measurement, which is what it used to do and is
+     * why Dragoon MS and Strata Dragoon MS read as the same bey.
+     */
+    const isComputed = market.origin === "computed";
+    if (isComputed)
+        return _jsx(ComputedMarketCard, { market: market });
+    const hasRange = market.p25 !== undefined && market.p75 !== undefined;
+    return (_jsxs(Stack, { gap: "sm", padding: "sm", rounded: "lg", border: "subtle", surface: "muted", className: "min-w-0", children: [_jsxs(Row, { align: "center", justify: "between", gap: "sm", wrap: true, className: "min-w-0", children: [_jsx(Badge, { variant: "secondary", children: market.inherited ? "Generation estimate" : "Typical asking price" }), market.sampleSize !== undefined && (_jsxs(Text, { size: "xs", color: "muted", children: [market.sampleSize, " ", market.sampleSize === 1 ? "listing" : "listings"] }))] }), market.inherited && (_jsxs(Text, { size: "sm", color: "muted", children: ["We have no figure for this exact item. These are typical asks for", " ", _jsx(Span, { weight: "semibold", children: market.viaName ?? market.viaCategoryId }), " as a whole, so every item in that generation shows the same range."] })), _jsxs(Row, { gap: "lg", wrap: true, className: "min-w-0", children: [hasRange && (_jsx(Figure, { label: "Usual low", value: money(market.p25), dim: market.inherited })), _jsx(Figure, { label: "Typical ask", value: money(market.median), dim: market.inherited }), hasRange && (_jsx(Figure, { label: "Usual high", value: money(market.p75), dim: market.inherited }))] }), soldOutPct !== null && (_jsxs(Text, { size: "sm", color: "muted", children: ["These are asking prices from other shops, and about ", soldOutPct, "% of listings at this level are sold out \u2014 so an ask is not proof anything changed hands at it."] })), _jsxs(Text, { size: "xs", color: "muted", className: "min-w-0 break-words", children: ["Aggregated from Indian shop listings", market.source ? ` · ${market.source}` : "", " \u00B7 tax-inclusive", market.asOf
                         ? ` · measured ${new Date(market.asOf).toLocaleDateString("en-IN")}`
                         : ""] })] }));
 }
+/**
+ * The per-leaf band computed from dated sightings.
+ *
+ * ## 🛑 The headline is the MODE, and it is labelled as one
+ *
+ * "Most commonly listed at" is a different claim from "typical ask" and the
+ * card has to make the right one. A median answers "what is the middle of this
+ * list"; a mode answers "what do people actually charge", and on a collectible
+ * those diverge — six sightings at ₹6,500 and three clearance ones at ₹3,000
+ * have a median that moves to ₹3,000 the moment two more cheap ones appear,
+ * while the going rate has not moved at all.
+ *
+ * ## 🛑 Where there is no mode, the label CHANGES
+ *
+ * `mode` is absent when no price bucket held two or more sightings — every
+ * observed price was different, so there is no cluster. The card then shows the
+ * median under "Typical ask". Printing a lone sighting under "most common"
+ * would dress one data point as a consensus.
+ *
+ * ## 🛑 `basedOnRecent` decides the low/high label, and it must
+ *
+ * False means the six-month window held too little to stand alone, so the
+ * figures are all-time. A card that says "last 6 months" over a two-year-old
+ * sighting is indistinguishable from an accurate one once printed — which is
+ * the whole reason the flag travels with the band instead of being inferred.
+ */
+function ComputedMarketCard({ market }) {
+    const recent = market.basedOnRecent === true;
+    const rangeLabel = recent ? "last 6 months" : "all time";
+    const hasRange = market.low !== undefined && market.high !== undefined;
+    return (_jsxs(Stack, { gap: "sm", padding: "sm", rounded: "lg", border: "default", className: "min-w-0", children: [_jsxs(Row, { align: "center", justify: "between", gap: "sm", wrap: true, className: "min-w-0", children: [_jsx(Badge, { variant: "primary", children: recent ? "Going rate · last 6 months" : "Going rate · all time" }), market.sampleSize !== undefined && (_jsxs(Text, { size: "xs", color: "muted", children: [market.sampleSize, " ", market.sampleSize === 1 ? "sighting" : "sightings"] }))] }), _jsxs(Row, { gap: "lg", wrap: true, className: "min-w-0", children: [hasRange && (_jsx(Figure, { label: `Lowest · ${rangeLabel}`, value: money(market.low) })), market.mode !== undefined ? (_jsx(Figure, { label: "Most commonly listed at", value: money(market.mode) })) : (_jsx(Figure, { label: "Typical ask", value: money(market.median) })), hasRange && (_jsx(Figure, { label: `Highest · ${rangeLabel}`, value: money(market.high) }))] }), market.mode !== undefined && market.modeCount !== undefined && (_jsxs(Text, { size: "sm", color: "muted", children: [market.modeCount, " of ", market.sampleSize, " sightings were around this price \u2014 it is the figure this item is listed at most often, not the middle of the range."] })), !recent && (_jsxs(Text, { size: "sm", color: "muted", children: ["Too few sightings in the last six months to stand on their own, so these cover everything we have recorded", market.lastSeenAt && relativeDay(market.lastSeenAt)
+                        ? ` — the newest is from ${relativeDay(market.lastSeenAt)}`
+                        : "", "."] })), _jsxs(Text, { size: "xs", color: "muted", className: "min-w-0 break-words", children: ["Asking prices from Indian shops and listings \u00B7 tax-inclusive", market.lastSeenAt
+                        ? ` · most recent sighting ${relativeDay(market.lastSeenAt) || new Date(market.lastSeenAt).toLocaleDateString("en-IN")}`
+                        : ""] })] }));
+}
 /**
  * What a signed-out visitor sees where the market band would be.
  *
@@ -155,7 +209,18 @@ function ResultCard({ row, threshold, market, canSeeMarket, }) {
              */
             _jsx(Text, { size: "sm", color: "muted", children: market
                     ? "Nothing has sold here on LetItRip yet, so the figures above are asking prices elsewhere rather than our own sales."
-                    : "No completed sales recorded here yet. Prices appear once something sells on LetItRip." }))] }));
+                    : canSeeMarket
+                        ? /*
+                           * 🛑 BOTH halves are empty here, and saying so is the point.
+                           * The old copy named only the sold half, so a lookup for an
+                           * item nobody has crawled either — Dragoon G and every other
+                           * Engine Gear top, an era the 2026-10 crawl skipped entirely —
+                           * read as "it just has not sold yet" when the truth is that we
+                           * have no price evidence of any kind. Those are different
+                           * states and only one of them is about our marketplace.
+                           */
+                            "No price evidence for this one yet — nothing sold here, and no asking prices recorded for it either. It appears as soon as either exists."
+                        : "No completed sales recorded here yet. Prices appear once something sells on LetItRip." }))] }));
 }
 /** Stable identity — a `useMemo` dependency inside `useSiteSearch`. */
 const identityLabel = (typeKey) => typeKey;

package/dist/features/price-index/market-stats.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Six months, the window the owner specified for "recent".
+ *
+ * 182 rather than 180: it is half of 365, so a year's data splits into exactly
+ * two windows and "the last six months" cannot quietly mean a different span
+ * depending on which months they were.
+ */
+export declare const RECENT_WINDOW_DAYS = 182;
+/**
+ * Below this, NO band is published for a leaf.
+ *
+ * Three, matching `PRICE_INDEX_MIN_CONFIDENT_SAMPLES` on the sold half — the
+ * two halves of this page must not disagree about what counts as evidence, and
+ * the sold half's reasoning ("a median of two sales is a coin flip presented as
+ * data") is about sample size, not about which side of the page it is on.
+ */
+export declare const MIN_BAND_OBSERVATIONS = 3;
+/**
+ * Below this, the band publishes a MEDIAN and no mode.
+ *
+ * A "most common price" derived from a bucket containing one sighting is not a
+ * most-common anything — it is that one sighting, relabelled. Two is the
+ * smallest number for which the word means what it says.
+ */
+export declare const MIN_MODE_OBSERVATIONS = 2;
+/** The minimum a sighting must carry to be counted. */
+export interface PriceObservationSample {
+    /** Decimal rupees, tax-inclusive — the basis every price in this app is on. */
+    amount: number;
+    /** When it was SEEN. Not when we wrote the row. */
+    seenAt: Date;
+}
+/** One computed band, plus everything a renderer needs to describe it. */
+export interface MarketStats {
+    /**
+     * The headline: the price sightings cluster on.
+     *
+     * 🛑 `undefined` when no bucket reached `MIN_MODE_OBSERVATIONS` — every
+     * sighting was a different price, so there is no cluster to report. The
+     * renderer falls back to `median` and must change its label when it does.
+     */
+    mode?: number;
+    /** How many sightings sat in the winning bucket. Absent with no mode. */
+    modeCount?: number;
+    /** Always present. The fallback headline, and context beside the mode. */
+    median: number;
+    low: number;
+    high: number;
+    sampleSize: number;
+    /**
+     * 🛑 FALSE means `low`/`high`/`mode` describe ALL TIME, because the
+     * six-month window held too little to stand on its own. The renderer must
+     * relabel rather than silently presenting old figures as current.
+     */
+    basedOnRecent: boolean;
+    /** The span actually used — `RECENT_WINDOW_DAYS`, or the full data span. */
+    windowDays: number;
+    /** The most recent sighting in the set the band was computed from. */
+    lastSeenAt: Date;
+}
+/**
+ * Bucket width by magnitude.
+ *
+ * Proportional rather than fixed, because a ₹50 bucket is three separate
+ * buckets across ₹99–₹249 part pricing and a rounding error on a ₹9,999 grail.
+ * The widths are ~2–5% of the value throughout, so "the same price" means the
+ * same thing at every price point.
+ */
+export declare function priceBucketWidth(amount: number): number;
+/**
+ * The band for one leaf, or `null` when there is not enough to say anything.
+ *
+ * 🛑 `null`, never a zeroed band. A band of ₹0 renders as a real figure meaning
+ * "this sells for nothing", which is strictly worse than silence — the same
+ * rule `CategoryPriceGuidance.sold` is held to ("absent until there are some —
+ * never zeroed").
+ *
+ * The recency decision happens ONCE here and is reported in `basedOnRecent`, so
+ * the job, the CLI and the renderer cannot each arrive at a different answer
+ * about which window a figure came from.
+ */
+export declare function computeMarketStats(samples: readonly PriceObservationSample[], now?: Date): MarketStats | null;