@mohasinac/appkit 4.14.0 → 4.15.0

package/dist/features/orders/repository/orders.repository.js

@@ -95,6 +95,11 @@ class OrderRepository extends BaseRepository {
             reason: ctx?.reason,
             note: ctx?.note,
             extraChanges: ctx?.extraChanges,
+            // `encryptPiiFields` is a flat top-level loop and never descends into
+            // arrays, so anything PII-named reaching `changes` would persist in
+            // PLAINTEXT inside statusHistory. None of ORDER_TRACKED_FIELDS is PII
+            // today — this is defence for the next field somebody adds.
+            piiFields: ORDER_PII_FIELDS,
             historyField: "statusHistory",
             truncatedField: "statusHistoryTruncated",
         });

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

@@ -24,12 +24,39 @@ export interface OrderSourceAuctionWon {
     /** Second-highest bid, when there was one. */
     runnerUpAmount?: number;
 }
+/**
+ * A buyout is a REAL BID, not a bid-free purchase.
+ *
+ * An earlier draft of this type asserted "zero bids BY DEFINITION, because
+ * buy-now is only valid while `!bidsHaveStarted`". That gate no longer
+ * exists: `buyNowAuction` places an actual `BidDocument` (`isBuyout: true`)
+ * plus a 1h locked cart line and leaves the auction **live**, and Buy Now is
+ * offered whenever `buyNowPrice` still beats the standing bid. Recording
+ * `bidCount: 0` would bake a falsehood into an immutable audit record.
+ *
+ * `standingBidAtBuyout` is the highest NON-buyout bid the buyout beat — read
+ * from the bids rather than `product.currentBid`, because a pending buyout
+ * deliberately never writes to that mirror.
+ *
+ * An unpaid buyout lapses to **`cancelled`**, not `forfeited`, and the seller
+ * is deliberately not notified: nothing was ever sold. That makes its
+ * timeline materially different from a lapsed auction win.
+ */
 export interface OrderSourceAuctionBuyNow {
     path: "auction-buy-now";
     auctionId: string;
+    /** The buyout bid itself — a buyout IS a bid. */
+    bidId: string;
     buyNowPrice: number;
     listPrice: number;
+    /** Highest non-buyout bid at the moment of buyout. 0 when nobody had bid. */
+    standingBidAtBuyout: number;
+    /** Active non-buyout bids at buyout time. NOT always zero. */
+    bidCount: number;
     boughtAt: Date;
+    /** `min(now + AUCTION_BUYOUT_WINDOW_MS, auctionEndDate)`. */
+    checkoutDeadline: Date;
+    auctionEndDate?: Date;
 }
 export interface OrderSourceOfferAccepted {
     path: "offer-accepted";
@@ -38,7 +65,15 @@ export interface OrderSourceOfferAccepted {
     /** The asking price at the moment the offer was made. */
     listPriceAtOffer: number;
     counterAmount?: number;
-    /** How many counter rounds before agreement. 0 = accepted outright. */
+    /**
+     * How many counter rounds before agreement. 1 = accepted outright.
+     *
+     * Read straight off the accepted offer's `counterRound`, which W2 made a
+     * persisted field. Before that this number was **unknowable**: each counter
+     * created an unlinked document and `previousOfferId` lived only inside a
+     * `serverLogger.info` call, so a three-round negotiation left no trace of
+     * having been one.
+     */
     counterRounds: number;
     acceptedBy: string;
     acceptedAt: Date;

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

@@ -2,7 +2,8 @@ import { type PaymentGateway, PaymentGatewayValues } from "../../payments/schema
 export { type PaymentGateway, PaymentGatewayValues };
 import type { ListingType } from "../../products/types/index";
 import type { OrderType } from "../utils/order-splitter";
-import type { AppliedOrderDiscount } from "../schemas/firestore";
+import type { AppliedOrderDiscount, OrderSourceContext } from "../schemas/firestore";
+import type { FieldChange } from "../../../_internal/shared/history/index";
 export type PaymentStatus = "pending" | "processing" | "paid" | "failed" | "refunded" | "partial_refund";
 export interface UserAddress {
     id: string;
@@ -46,12 +47,34 @@ export interface OrderItem {
     /** Snapshot of bundle.bundleProductIds at order-creation time. */
     bundleProductIds?: string[];
 }
-export interface OrderTimeline {
-    status: OrderStatus;
-    message?: string;
-    timestamp: string;
-    actor?: string;
+/**
+ * One entry on an order's timeline — the client-facing shape of
+ * `StatusChangeEntry`, with dates as ISO strings.
+ *
+ * The previous declaration here was `{status, message?, timestamp, actor?}`
+ * and had **zero writers** in the entire codebase since the day it was
+ * added, so nothing depended on it. `OrderStatusTimeline` synthesised its
+ * steps from four scalar date fields instead, which meant any transition
+ * without a dedicated date field — payment reviewed, proof re-upload asked
+ * for, a partial refund posted — could not appear at all.
+ */
+export interface OrderTimelineEntry {
+    at: string;
+    actorUid?: string;
+    actorRole: "buyer" | "seller" | "admin" | "system";
+    /**
+     * Delta only: `{ status: { from: "confirmed", to: "shipped" } }`.
+     * Reuses the primitive's `FieldChange` rather than restating the shape, so
+     * the client type cannot drift from what the repository writes.
+     */
+    changes: Record<string, FieldChange>;
+    reason?: string;
+    note?: string;
+    /** The function or job that caused it — what the timeline renders by. */
+    trigger: string;
 }
+/** @deprecated Use {@link OrderTimelineEntry}. Kept only to avoid breaking a stale import. */
+export type OrderTimeline = OrderTimelineEntry;
 export interface Order {
     id: string;
     userId: string;
@@ -108,7 +131,12 @@ export interface Order {
     /** Carrier tracking page URL — rendered as an external link that opens in a new tab. No live-tracking API integration; this is just the passthrough URL a seller/admin entered. */
     trackingUrl?: string;
     notes?: string;
-    timeline?: OrderTimeline[];
+    /** Real recorded transitions — see {@link OrderTimelineEntry}. */
+    timeline?: OrderTimelineEntry[];
+    /** Entries trimmed off the front of the capped history, if any. */
+    timelineTruncated?: number;
+    /** How the buyer acquired the right to buy. Written once, at creation. */
+    sourceContext?: OrderSourceContext;
     physicalLocation?: {
         zone: string;
         shelf: string;

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

@@ -235,7 +235,11 @@ export function GroupSettingsPanel({ productId, productSlug, groupId, isGroupPar
                     setOpen(next);
                     if (next && isGroupParent && children === null)
                         loadChildren();
-                }, paddingX: "none", paddingY: "xs", justify: "between", className: "w-full text-left group", "aria-expanded": open, children: [_jsx(Heading, { level: 3, size: "sm", weight: "semibold", color: "muted", children: "Group Settings" }), _jsx(Span, { size: "xs", className: "group-hover:text-[var(--appkit-color-text-muted)] dark:group-hover:text-[var(--appkit-color-text-faint)] transition-colors", color: "faint", children: open ? "▲" : "▼" })] }), open && (_jsxs(Stack, { gap: "sm", className: `mt-3 ${__P.p4}`, surface: "muted", rounded: "lg", border: "default", children: [!groupId && !groupParentSlug && (_jsxs(Stack, { gap: "xs", children: [_jsx(Text, { size: "xs", color: "muted", children: "Group related listings together \u2014 e.g. a set, bundle, or multi-part item. Parts can be sold individually but shown together." }), _jsx(Button, { type: "button", variant: "secondary", size: "sm", onClick: startGroup, isLoading: loading, children: "Start a group" })] })), isGroupParent && groupId && (_jsxs(Stack, { gap: "md", children: [_jsxs(FormShellContext.Provider, { value: titleShellCtx, children: [_jsxs(Row, { align: "start", gap: "sm", wrap: true, children: [_jsx(Div, { className: "flex-1 min-w-[200px]", children: _jsx(FormField, { name: "groupTitle", label: "Group title", type: "text", value: editTitle, onChange: setEditTitle, placeholder: "e.g. Human Toy Complete Set" }) }), _jsx(Div, { padding: "t-lg", children: _jsx(Button, { type: "button", variant: "secondary", size: "sm", onClick: saveTitle, isLoading: loading, children: "Save title" }) })] }), _jsx(FormErrorSummary, {})] }), _jsxs(Div, { children: [_jsxs(Text, { className: "mb-2", color: "muted", size: "xs", weight: "semibold", children: ["Members (", childSlugsCount + 1, " \u2014 including this listing)"] }), loading && !children ? (_jsx(Text, { size: "xs", color: "faint", children: "Loading\u2026" })) : (_jsxs(Div, { className: "divide-y divide-zinc-100 divide-[var(--appkit-color-border-subtle)]", children: [_jsxs(Row, { align: "center", gap: "sm", padding: "y-xs", children: [_jsx(Span, { padding: "pill-2xs", weight: "semibold", className: "bg-[var(--appkit-color-primary)]/10 text-[var(--appkit-color-primary)] text-[10px]", rounded: "default", children: "Parent" }), _jsx(Text, { className: "flex-1", color: "primary", size: "sm", children: productSlug })] }), (children ?? []).filter((c) => c.id !== productId).map((child) => (_jsxs(Row, { align: "center", gap: "sm", padding: "y-xs", children: [child.images?.[0] ? (_jsx(Div, { className: "relative w-8 h-8 flex-shrink-0 border border-[var(--appkit-color-border)]", rounded: "full", overflow: "hidden", children: _jsx(MediaImage, { src: child.images[0], alt: child.title, size: "thumbnail" }) })) : (_jsx(Div, { className: "w-8 h-8", surface: "subtle", rounded: "full" })), _jsx(Text, { className: "flex-1 truncate", color: "primary", size: "sm", children: child.title }), _jsx(Button, { type: "button", variant: "ghost", size: "sm", onClick: () => requestUnlinkChild(child.id), isLoading: loading, className: `${CLS_DELETE_LINK} text-[length:var(--appkit-text-xs)]`, children: "Unlink" })] }, child.id)))] }))] }), _jsxs(Row, { gap: "sm", wrap: true, children: [_jsx(Button, { type: "button", variant: "secondary", size: "sm", onClick: () => setShowAddModal(true), children: "Add child listing" }), _jsx(Button, { type: "button", variant: "ghost", size: "sm", onClick: requestDissolveGroup, isLoading: loading, className: CLS_DELETE_LINK, children: "Dissolve group" })] })] })), !isGroupParent && groupParentSlug && (_jsxs(Stack, { gap: "xs", children: [_jsxs(Text, { size: "sm", color: "muted", children: ["Part of:", " ", _jsx(Span, { weight: "medium", color: "primary", children: groupTitle ?? groupParentSlug })] }), _jsxs(Text, { size: "xs", color: "muted", children: ["Parent listing: ", _jsx(Code, { className: "font-mono", children: groupParentSlug })] }), _jsx(Button, { type: "button", variant: "ghost", size: "sm", onClick: requestLeaveGroup, isLoading: loading, className: `${CLS_DELETE_LINK} w-fit`, children: "Leave group" })] }))] })), (groupChildSlugs?.length ?? 0) >= 4 ? (_jsx(SideDrawer, { isOpen: showAddModal, onClose: () => setShowAddModal(false), title: "Add child listing", children: _jsx(AddChildContent, { addTab: addTab, setAddTab: setAddTab, createForm: createForm, setCreateForm: setCreateForm, productSlug: productSlug, storeProductsEndpoint: storeProductsEndpoint, linkTargets: linkTargets, setLinkTargets: setLinkTargets, onAddCreate: addCreateChild, onAddLink: addLinkChild, loading: loading }) })) : (_jsx(Modal, { open: showAddModal, onClose: () => setShowAddModal(false), title: "Add child listing", size: "lg", children: _jsx(AddChildContent, { addTab: addTab, setAddTab: setAddTab, createForm: createForm, setCreateForm: setCreateForm, productSlug: productSlug, storeProductsEndpoint: storeProductsEndpoint, linkTargets: linkTargets, setLinkTargets: setLinkTargets, onAddCreate: addCreateChild, onAddLink: addLinkChild, loading: loading }) })), confirmAction && (_jsx(ConfirmDeleteModal, { isOpen: true, title: confirmAction.title, message: confirmAction.message, onConfirm: confirmAction.onConfirm, onClose: () => setConfirmAction(null), isDeleting: loading }))] }));
+                }, paddingX: "none", paddingY: "xs", justify: "between", className: "w-full text-left group", "aria-expanded": open, children: [_jsx(Heading, { level: 3, size: "sm", weight: "semibold", color: "muted", children: "Group Settings" }), _jsx(Span, { size: "xs", className: "group-hover:text-[var(--appkit-color-text-muted)] dark:group-hover:text-[var(--appkit-color-text-faint)] transition-colors", color: "faint", children: open ? "▲" : "▼" })] }), open && (_jsxs(Stack, { gap: "sm", className: `mt-3 ${__P.p4}`, surface: "muted", rounded: "lg", border: "default", children: [!groupId && !groupParentSlug && (_jsxs(Stack, { gap: "xs", children: [_jsx(Text, { size: "xs", color: "muted", children: "Group related listings together \u2014 e.g. a set, bundle, or multi-part item. Parts can be sold individually but shown together." }), _jsx(Button, { type: "button", variant: "secondary", size: "sm", onClick: startGroup, isLoading: loading, children: "Start a group" })] })), isGroupParent && groupId && (_jsxs(Stack, { gap: "md", children: [_jsxs(FormShellContext.Provider, { value: titleShellCtx, children: [_jsxs(Row, { align: "start", gap: "sm", wrap: true, children: [_jsx(Div, { className: "flex-1 min-w-[200px]", children: _jsx(FormField, { name: "groupTitle", label: "Group title", type: "text", value: editTitle, onChange: setEditTitle, placeholder: "e.g. Human Toy Complete Set" }) }), _jsx(Div, { padding: "t-lg", children: _jsx(Button, { type: "button", variant: "secondary", size: "sm", onClick: saveTitle, isLoading: loading, children: "Save title" }) })] }), _jsx(FormErrorSummary, {})] }), _jsxs(Div, { children: [_jsxs(Text, { className: "mb-2", color: "muted", size: "xs", weight: "semibold", children: ["Members (", childSlugsCount + 1, " \u2014 including this listing)"] }), loading && !children ? (_jsx(Text, { size: "xs", color: "faint", children: "Loading\u2026" })) : (_jsxs(Div, { className: "divide-y divide-zinc-100 divide-[var(--appkit-color-border-subtle)]", children: [_jsxs(Row, { align: "center", gap: "sm", padding: "y-xs", children: [_jsx(Span, { padding: "pill-2xs", weight: "semibold", className: "bg-[var(--appkit-color-primary)]/10 text-[var(--appkit-color-primary)] text-[10px]", rounded: "default", children: "Parent" }), _jsx(Text, { className: "flex-1", color: "primary", size: "sm", children: productSlug })] }), (children ?? []).filter((c) => c.id !== productId).map((child) => (_jsxs(Row, { align: "center", gap: "sm", padding: "y-xs", children: [child.images?.[0] ? (_jsx(Div, { className: "relative w-8 h-8 flex-shrink-0 border border-[var(--appkit-color-border)]", rounded: "full", overflow: "hidden", children: _jsx(MediaImage, { src: child.images[0], alt: child.title, size: "thumbnail" }) })) : (_jsx(Div, { className: "w-8 h-8", surface: "subtle", rounded: "full" })), _jsx(Text, { className: "flex-1 truncate", color: "primary", size: "sm", children: child.title }), _jsx(Button, { type: "button", variant: "ghost", size: "sm", onClick: () => requestUnlinkChild(child.id), isLoading: loading, className: `${CLS_DELETE_LINK} text-[length:var(--appkit-text-xs)]`, children: "Unlink" })] }, child.id)))] }))] }), _jsxs(Row, { gap: "sm", wrap: true, children: [_jsx(Button, { type: "button", variant: "secondary", size: "sm", onClick: () => setShowAddModal(true), children: "Add child listing" }), _jsx(Button, { type: "button", variant: "ghost", size: "sm", onClick: requestDissolveGroup, isLoading: loading, className: CLS_DELETE_LINK, children: "Dissolve group" })] })] })), !isGroupParent && groupParentSlug && (_jsxs(Stack, { gap: "xs", children: [_jsxs(Text, { size: "sm", color: "muted", children: ["Part of:", " ", _jsx(Span, { weight: "medium", color: "primary", children: groupTitle ?? groupParentSlug })] }), _jsxs(Text, { size: "xs", color: "muted", children: ["Parent listing: ", _jsx(Code, { className: "font-mono", children: groupParentSlug })] }), _jsx(Button, { type: "button", variant: "ghost", size: "sm", onClick: requestLeaveGroup, isLoading: loading, className: `${CLS_DELETE_LINK} w-fit`, children: "Leave group" })] }))] })), (() => {
+                const content = (_jsx(AddChildContent, { addTab: addTab, setAddTab: setAddTab, createForm: createForm, setCreateForm: setCreateForm, productSlug: productSlug, storeProductsEndpoint: storeProductsEndpoint, linkTargets: linkTargets, setLinkTargets: setLinkTargets, onAddCreate: addCreateChild, onAddLink: addLinkChild, loading: loading }));
+                const close = () => setShowAddModal(false);
+                return (groupChildSlugs?.length ?? 0) >= 4 ? (_jsx(SideDrawer, { isOpen: showAddModal, onClose: close, title: "Add child listing", children: content })) : (_jsx(Modal, { open: showAddModal, onClose: close, title: "Add child listing", size: "lg", children: content }));
+            })(), confirmAction && (_jsx(ConfirmDeleteModal, { isOpen: true, title: confirmAction.title, message: confirmAction.message, onConfirm: confirmAction.onConfirm, onClose: () => setConfirmAction(null), isDeleting: loading }))] }));
 }
 function AddChildContent({ addTab, setAddTab, createForm, setCreateForm, productSlug, storeProductsEndpoint, linkTargets, setLinkTargets, onAddCreate, onAddLink, loading, }) {
     const { shellCtx, validate } = useFormShellState(createChildSchema);

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

@@ -377,7 +377,7 @@ export declare const productItemSchema: z.ZodObject<{
     preOrderDepositAmount?: number | undefined;
     preOrderMaxQuantity?: number | undefined;
     preOrderCurrentCount?: number | undefined;
-    preOrderProductionStatus?: "in_production" | "upcoming" | "ready_to_ship" | undefined;
+    preOrderProductionStatus?: "upcoming" | "in_production" | "ready_to_ship" | undefined;
     preOrderCancellable?: boolean | undefined;
     isPromoted?: boolean | undefined;
     pickupAddressId?: string | undefined;
@@ -516,7 +516,7 @@ export declare const productItemSchema: z.ZodObject<{
     preOrderDepositAmount?: number | undefined;
     preOrderMaxQuantity?: number | undefined;
     preOrderCurrentCount?: number | undefined;
-    preOrderProductionStatus?: "in_production" | "upcoming" | "ready_to_ship" | undefined;
+    preOrderProductionStatus?: "upcoming" | "in_production" | "ready_to_ship" | undefined;
     preOrderCancellable?: boolean | undefined;
     isPromoted?: boolean | undefined;
     pickupAddressId?: string | undefined;

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

@@ -102,6 +102,79 @@ export declare const productFeatureUpdateSchema: z.ZodObject<{
     iconColor?: string | undefined;
     productTypes?: ("all" | "classified" | "auction" | "prize-draw" | "digital-code" | "live" | "product" | "preorder")[] | undefined;
 }>;
+/**
+ * The FORM schema for the product-feature editor, with UI metadata.
+ *
+ * `AdminFeatureEditorView` had **no validation whatsoever** before W5 — ten
+ * `useState` fields, `required` on the inputs (an HTML attribute any
+ * programmatic submit bypasses), and nothing else. Meanwhile these validators
+ * had existed all along and simply were not wired: the "schema exists, the
+ * consumer ignores it" case the plan catalogues.
+ *
+ * It reuses `productFeatureAdminCreateSchema`'s field shapes rather than
+ * restating them — a second copy of the same bounds is how the two would come
+ * to disagree. Only the annotations are new.
+ *
+ * 🛑 `annotate()` must be the OUTERMOST call — it keys a WeakMap by schema
+ * instance and every zod wrapper returns a new one.
+ */
+export declare const productFeatureFormSchema: z.ZodEffects<z.ZodObject<{
+    label: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    icon: z.ZodString;
+    iconColor: z.ZodOptional<z.ZodString>;
+    category: z.ZodEnum<["shipping", "seller", "condition", "platform", "auction", "preorder", "custom"]>;
+    scope: z.ZodEnum<["platform", "store"]>;
+    productTypes: z.ZodArray<z.ZodEnum<["product", "auction", "preorder", "prize-draw", "classified", "digital-code", "live", "all"]>, "many">;
+    storeId: z.ZodOptional<z.ZodString>;
+    isActive: z.ZodBoolean;
+    displayOrder: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    label: string;
+    scope: "store" | "platform";
+    icon: string;
+    category: "shipping" | "custom" | "seller" | "condition" | "auction" | "platform" | "preorder";
+    isActive: boolean;
+    displayOrder: number;
+    productTypes: ("all" | "classified" | "auction" | "prize-draw" | "digital-code" | "live" | "product" | "preorder")[];
+    storeId?: string | undefined;
+    description?: string | undefined;
+    iconColor?: string | undefined;
+}, {
+    label: string;
+    scope: "store" | "platform";
+    icon: string;
+    category: "shipping" | "custom" | "seller" | "condition" | "auction" | "platform" | "preorder";
+    isActive: boolean;
+    displayOrder: number;
+    productTypes: ("all" | "classified" | "auction" | "prize-draw" | "digital-code" | "live" | "product" | "preorder")[];
+    storeId?: string | undefined;
+    description?: string | undefined;
+    iconColor?: string | undefined;
+}>, {
+    label: string;
+    scope: "store" | "platform";
+    icon: string;
+    category: "shipping" | "custom" | "seller" | "condition" | "auction" | "platform" | "preorder";
+    isActive: boolean;
+    displayOrder: number;
+    productTypes: ("all" | "classified" | "auction" | "prize-draw" | "digital-code" | "live" | "product" | "preorder")[];
+    storeId?: string | undefined;
+    description?: string | undefined;
+    iconColor?: string | undefined;
+}, {
+    label: string;
+    scope: "store" | "platform";
+    icon: string;
+    category: "shipping" | "custom" | "seller" | "condition" | "auction" | "platform" | "preorder";
+    isActive: boolean;
+    displayOrder: number;
+    productTypes: ("all" | "classified" | "auction" | "prize-draw" | "digital-code" | "live" | "product" | "preorder")[];
+    storeId?: string | undefined;
+    description?: string | undefined;
+    iconColor?: string | undefined;
+}>;
+export type ProductFeatureFormValues = z.infer<typeof productFeatureFormSchema>;
 export type ProductFeatureAdminCreatePayload = z.infer<typeof productFeatureAdminCreateSchema>;
 export type ProductFeatureStoreCreatePayload = z.infer<typeof productFeatureStoreCreateSchema>;
 export type ProductFeatureUpdatePayload = z.infer<typeof productFeatureUpdateSchema>;

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

@@ -6,6 +6,7 @@
  * of hand-rolling parallel schemas.
  */
 import { z } from "zod";
+import { annotate } from "../../shell/field-ui-meta";
 export const PRODUCT_FEATURE_PRODUCT_TYPE_ENUM = z.enum([
     "product",
     "auction",
@@ -66,3 +67,65 @@ export const productFeatureUpdateSchema = z.object({
     isActive: z.boolean().optional(),
     displayOrder: z.number().int().min(0).max(FEATURE_DISPLAY_ORDER_MAX).optional(),
 });
+/**
+ * The FORM schema for the product-feature editor, with UI metadata.
+ *
+ * `AdminFeatureEditorView` had **no validation whatsoever** before W5 — ten
+ * `useState` fields, `required` on the inputs (an HTML attribute any
+ * programmatic submit bypasses), and nothing else. Meanwhile these validators
+ * had existed all along and simply were not wired: the "schema exists, the
+ * consumer ignores it" case the plan catalogues.
+ *
+ * It reuses `productFeatureAdminCreateSchema`'s field shapes rather than
+ * restating them — a second copy of the same bounds is how the two would come
+ * to disagree. Only the annotations are new.
+ *
+ * 🛑 `annotate()` must be the OUTERMOST call — it keys a WeakMap by schema
+ * instance and every zod wrapper returns a new one.
+ */
+export const productFeatureFormSchema = z.object({
+    label: annotate(productFeatureAdminCreateSchema.shape.label, {
+        section: "basics", sectionLabel: "Feature", sectionRequired: true,
+        quick: true, order: 1, row: "full",
+    }),
+    description: annotate(productFeatureAdminCreateSchema.shape.description, {
+        section: "basics", order: 2, row: "full",
+    }),
+    icon: annotate(productFeatureAdminCreateSchema.shape.icon, {
+        section: "basics", quick: true, order: 3, row: "pair",
+    }),
+    iconColor: annotate(productFeatureAdminCreateSchema.shape.iconColor, {
+        section: "basics", order: 4, row: "pair",
+    }),
+    category: annotate(productFeatureAdminCreateSchema.shape.category, {
+        section: "scope", sectionLabel: "Scope & Applicability",
+        quick: true, order: 1, row: "pair",
+    }),
+    scope: annotate(productFeatureAdminCreateSchema.shape.scope, {
+        section: "scope", quick: true, order: 2, row: "pair",
+    }),
+    productTypes: annotate(productFeatureAdminCreateSchema.shape.productTypes, {
+        section: "scope", order: 3, row: "full", kind: "list",
+    }),
+    storeId: annotate(productFeatureAdminCreateSchema.shape.storeId, {
+        section: "scope", order: 4, row: "pair",
+        help: "Only used when scope is \"store\".",
+    }),
+    isActive: annotate(productFeatureAdminCreateSchema.shape.isActive, {
+        section: "visibility", sectionLabel: "Visibility", order: 1, row: "quarter",
+    }),
+    displayOrder: annotate(productFeatureAdminCreateSchema.shape.displayOrder, {
+        section: "visibility", order: 2, row: "pair",
+    }),
+}).superRefine((v, ctx) => {
+    // The one rule no per-field bound can state: a store-scoped feature must
+    // name its store. The server enforces it too — this exists so the admin is
+    // told before submitting rather than by a 400.
+    if (v.scope === "store" && !v.storeId?.trim()) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["storeId"],
+            message: "A store-scoped feature must name a store.",
+        });
+    }
+});

package/dist/features/scams/constants/scammer-status-display.d.ts

@@ -0,0 +1,28 @@
+import { type ScammerStatus } from "../schemas/firestore";
+/** Human-readable label. Replaces two `.replace(/_/g, " ")` call sites, which
+ *  rendered "pending review" — mechanically correct, and not a written label. */
+export declare const SCAMMER_STATUS_LABEL: Record<ScammerStatus, string>;
+/**
+ * Inline-chip styling. Every entry is a `bg-{status}-surface` + `text-{status}`
+ * pair per Recurrent Root Cause #67 — the two tokens invert together with the
+ * theme, which a literal `text-white` would not.
+ *
+ * `removed` is the neutral case: it has no status colour because it is not a
+ * status outcome, it is a withdrawal. ONE background, ONE ink.
+ */
+export declare const SCAMMER_STATUS_BADGE: Record<ScammerStatus, string>;
+/** Dropdown options, derived from the union so one cannot go missing. */
+export declare const SCAMMER_STATUS_OPTIONS: {
+    value: "verified" | "rejected" | "removed" | "pending_review";
+    label: string;
+}[];
+/**
+ * Narrow an unknown API value to a real status.
+ *
+ * The list view used `toStringValue(item.status, "pending_review")`, which
+ * produces a `string` — so an unrecognised value flowed on as if it were a
+ * status and every consumer fell back to the pending styling. This maps
+ * anything unrecognised to `pending_review` explicitly, and the return type
+ * says so.
+ */
+export declare function toScammerStatus(value: unknown): ScammerStatus;

package/dist/features/scams/constants/scammer-status-display.js

@@ -0,0 +1,79 @@
+/*
+ * WHY: "How does a scammer status look and read" had FOUR hand-written answers
+ *      and they had already diverged in a way that shipped a real defect:
+ *
+ *        · `AdminScammersView.STATUS_BADGE`   — Record<string, string>
+ *        · `AdminScammerEditorView.STATUS_COLOR` — Record<string, string>
+ *        · `AdminScammerEditorView.STATUS_OPTIONS` — a literal label list
+ *        · `ADMIN_SCAMMER_STATUS_TABS`        — the filter chips
+ *
+ *      Both colour maps carried the SAME broken `removed` entry:
+ *
+ *          "bg-[…surface] text-[…muted] bg-[…surface-elevated] text-[…muted]"
+ *
+ *      — two backgrounds and two inks on one element. Tailwind emits all four
+ *      and the winner is decided by stylesheet order, not by position in the
+ *      class string, so which background actually painted was not what either
+ *      map said. One bug, two copies: the Duplication Framework's bug-fix
+ *      multiplier, which is what makes this a consolidate rather than a
+ *      third copy.
+ *
+ * WHAT: One display module beside the union it describes.
+ *
+ * ## Everything here is keyed `Record<ScammerStatus, …>`
+ *
+ * Not `Record<string, …>`. A status added to the union without a label or a
+ * badge is then a COMPILE error rather than a row that silently renders with
+ * the fallback styling of a status it is not — which is precisely how the
+ * loose maps hid the broken `removed` entry.
+ *
+ * EXPORTS:
+ *   SCAMMER_STATUS_LABEL, SCAMMER_STATUS_BADGE, SCAMMER_STATUS_OPTIONS,
+ *   toScammerStatus
+ *
+ * @tag domain:scams
+ * @tag layer:constants
+ * @tag pattern:none
+ * @tag access:isomorphic
+ * @tag consumers:AdminScammersView,AdminScammerEditorView
+ * @tag sideEffects:none
+ */
+import { ScammerStatusValues } from "../schemas/firestore";
+/** Human-readable label. Replaces two `.replace(/_/g, " ")` call sites, which
+ *  rendered "pending review" — mechanically correct, and not a written label. */
+export const SCAMMER_STATUS_LABEL = {
+    pending_review: "Pending review",
+    verified: "Verified",
+    rejected: "Rejected",
+    removed: "Removed",
+};
+/**
+ * Inline-chip styling. Every entry is a `bg-{status}-surface` + `text-{status}`
+ * pair per Recurrent Root Cause #67 — the two tokens invert together with the
+ * theme, which a literal `text-white` would not.
+ *
+ * `removed` is the neutral case: it has no status colour because it is not a
+ * status outcome, it is a withdrawal. ONE background, ONE ink.
+ */
+export const SCAMMER_STATUS_BADGE = {
+    pending_review: "bg-warning-surface text-warning",
+    verified: "bg-success-surface text-success",
+    rejected: "bg-error-surface text-error",
+    removed: "bg-[var(--appkit-color-surface-elevated)] text-[var(--appkit-color-text-muted)]",
+};
+/** Dropdown options, derived from the union so one cannot go missing. */
+export const SCAMMER_STATUS_OPTIONS = Object.values(ScammerStatusValues).map((value) => ({ value, label: SCAMMER_STATUS_LABEL[value] }));
+/**
+ * Narrow an unknown API value to a real status.
+ *
+ * The list view used `toStringValue(item.status, "pending_review")`, which
+ * produces a `string` — so an unrecognised value flowed on as if it were a
+ * status and every consumer fell back to the pending styling. This maps
+ * anything unrecognised to `pending_review` explicitly, and the return type
+ * says so.
+ */
+export function toScammerStatus(value) {
+    return Object.values(ScammerStatusValues).includes(value)
+        ? value
+        : ScammerStatusValues.PENDING_REVIEW;
+}

package/dist/features/seller/actions/offer-actions.js

@@ -210,7 +210,24 @@ export async function counterOfferByBuyer(userId, userEmail, input) {
     const offerCount = await offerRepository.countByBuyerAndProduct(userId, offer.productId, product.updatedAt);
     if (offerCount >= 3)
         throw new ValidationError(ERROR_MESSAGES.OFFER.LIMIT_REACHED);
-    await offerRepository.withdraw(offerId);
+    // ── Create BEFORE superseding. Order matters. ───────────────────────────
+    //
+    // This used to `withdraw()` first and `create()` second. If `create` threw —
+    // a validation slip, a Firestore blip — the buyer's live counter was ALREADY
+    // withdrawn, no replacement existed, the negotiation was dead, and one of
+    // their three offer slots had been burnt for nothing.
+    //
+    // Reversed, the worst failure is a transient extra pending offer, which
+    // `hasActiveOffer` and the expiry sweep both already handle.
+    //
+    // The chain fields are what make a multi-round negotiation readable at all:
+    // `previousOfferId` used to exist ONLY inside the serverLogger call below
+    // and never reached Firestore, so three rounds were three unrelated
+    // documents. `chainRootOfferId` is denormalised onto every round so a list
+    // row can render "Round 2" with zero extra reads, and `findChain` stays a
+    // single-field equality served by the automatic index.
+    const chainRoot = offer.chainRootOfferId ?? offer.id;
+    const nextRound = (offer.counterRound ?? 1) + 1;
     const newOffer = await offerRepository.create({
         productId: offer.productId,
         productTitle: offer.productTitle,
@@ -225,7 +242,18 @@ export async function counterOfferByBuyer(userId, userEmail, input) {
         listedPrice: offer.listedPrice,
         currency: offer.currency,
         buyerNote,
+        // NOT carrying `sellerNote` forward: it would render as "Seller note" on
+        // the new round, making the seller look like they had already answered a
+        // counter they have never seen. Round N-1 keeps its own note and is now
+        // reachable via `previousOfferId`.
+        previousOfferId: offer.id,
+        chainRootOfferId: chainRoot,
+        counterRound: nextRound,
     });
+    // Now supersede the old round — one write, one history entry. A `withdrawn`
+    // document carrying `supersededByOfferId` renders as *Superseded* (neutral),
+    // not *Withdrawn* (negative): the buyer did not walk away, they countered.
+    await offerRepository.withdraw(offerId, newOffer.id, { actor: { uid: userId, role: "buyer" } }, offer);
     const buyerCounterStore = offer.storeId ? await storeRepository.findById(offer.storeId) : null;
     if (buyerCounterStore?.ownerId)
         await sendNotification({
@@ -237,12 +265,14 @@ export async function counterOfferByBuyer(userId, userEmail, input) {
             relatedId: newOffer.id,
             relatedType: "offer",
         });
+    // `previousOfferId` is no longer logged as its only record — it is a
+    // persisted field on `newOffer` now. A log line is not a data model.
     serverLogger.info("counterOfferByBuyer", {
-        previousOfferId: offerId,
         newOfferId: newOffer.id,
         buyerUid: userId,
         productId: offer.productId,
         counterAmount,
+        counterRound: nextRound,
     });
     return newOffer;
 }

package/dist/features/seller/components/OfferPhaseTimeline.d.ts

@@ -0,0 +1,59 @@
+/**
+ * OfferPhaseTimeline — the offer-shaped wrapper around `<StatusTimeline>`.
+ *
+ * An offer is an order with more phases in front of it, so it shares the rail
+ * and supplies only its own vocabulary:
+ *
+ *   made → countered → accepted → paid
+ *   with declined / withdrawn / expired as the terminal-negative branch
+ *
+ * ## `superseded` is a RENDER KEY, never an OfferStatus
+ *
+ * A document that is `withdrawn` **and** carries `supersededByOfferId` is not
+ * a walk-away — the buyer countered, and the negotiation continued into the
+ * next round. It renders neutral ("Superseded"), not negative ("Withdrawn").
+ *
+ * Deliberately NOT an eighth `OfferStatus` value: `ADMIN_OFFER_STATUS_TABS`
+ * would then gain a chip that matches zero stored rows, which is exactly the
+ * defect `audit-filter-tab-enums` exists to catch.
+ *
+ * ## Back-compat
+ *
+ * Offers written before `statusHistory` existed have none. Branch B derives
+ * what it can from the scalars — and `expired` gets **no date at all**,
+ * because `expireMany` never wrote one. `updatedAt` is "last write of any
+ * kind" and `expiresAt` is a deadline, not an event; using either would be a
+ * fabricated timestamp.
+ */
+import { type TimelineEntry } from "../../status-history/components/StatusTimeline";
+/** One round of a negotiation, as returned by the API. */
+export interface OfferChainRound {
+    id: string;
+    counterRound: number;
+    status: string;
+    offerAmount: number;
+    counterAmount?: number;
+    superseded: boolean;
+    createdAt: string;
+    respondedAt?: string;
+    sellerNote?: string;
+    buyerNote?: string;
+}
+export interface OfferPhaseTimelineProps {
+    status: string;
+    timeline?: TimelineEntry[];
+    timelineTruncated?: number;
+    superseded?: boolean;
+    createdAt?: string;
+    respondedAt?: string;
+    acceptedAt?: string;
+    paidAt?: string;
+    /**
+     * Earlier rounds, oldest first. Concatenated ahead of this offer's own
+     * steps into ONE rail, each introduced by a "Round N" divider — a
+     * negotiation reads as one story, not N disconnected cards.
+     */
+    chain?: OfferChainRound[];
+    className?: string;
+}
+export declare function OfferPhaseTimeline({ status, timeline, timelineTruncated, superseded, createdAt, respondedAt, acceptedAt, paidAt, chain, className, }: OfferPhaseTimelineProps): import("react").JSX.Element;