@mohasinac/appkit 4.59.0 → 4.60.1

package/dist/features/admin/components/analytics/AdminStatCard.js

@@ -11,7 +11,82 @@ const GRADIENTS = {
     amber: "var(--appkit-gradient-warning-stat)",
     rose: "var(--appkit-gradient-danger-stat)",
 };
-export function AdminStatCard({ label, value, sub, icon, gradient = "brand", className = "", }) {
+/**
+ * A 40×24 trend line. Deliberately NOT recharts.
+ *
+ * 🛑 recharts IS installed and is used for the three real charts in this app —
+ * but it is a ~100 KB client bundle with a `ResponsiveContainer` that measures
+ * on mount, and a dashboard home renders six to eight of these. Six
+ * ResizeObservers to draw six polylines is a layout-thrash and a bundle cost
+ * for 24 pixels of decoration. An inline `<svg>` with a `<polyline>` is the
+ * whole feature.
+ *
+ * `preserveAspectRatio="none"` so the line fills its box at any size: the
+ * values are normalised to 0–100 here, so the viewBox IS the data range and
+ * stretching it is correct rather than distorting.
+ */
+function Sparkline({ series, rising, }) {
+    const min = Math.min(...series);
+    const max = Math.max(...series);
+    /*
+     * 🛑 A FLAT SERIES IS DRAWN FLAT, not divided by zero. When every value is
+     * equal `max - min` is 0; the guard puts the line down the middle, which is
+     * what "no change" looks like. Without it every point becomes NaN and the
+     * polyline silently renders nothing — a missing sparkline that reads as
+     * "no data" about a series that is simply steady.
+     */
+    const span = max - min || 1;
+    const points = series
+        .map((v, i) => {
+        const x = (i / (series.length - 1)) * 100;
+        // SVG y grows downward, so the value is inverted.
+        const y = 100 - ((v - min) / span) * 100;
+        return `${x.toFixed(2)},${y.toFixed(2)}`;
+    })
+        .join(" ");
+    return (_jsx("svg", { viewBox: "0 0 100 100", preserveAspectRatio: "none", className: "h-full w-full", focusable: "false", children: _jsx("polyline", { points: points, fill: "none", stroke: rising
+                ? "var(--appkit-color-success)"
+                : "var(--appkit-color-error)", strokeWidth: 6, strokeLinecap: "round", strokeLinejoin: "round", vectorEffect: "non-scaling-stroke" }) }));
+}
+export function AdminStatCard({ label, value, sub, icon, gradient = "brand", className = "", trendPercent, trendLabel, higherIsBetter = true, series, }) {
     const resolvedGradient = GRADIENTS[gradient] ?? gradient;
-    return (_jsxs(Div, { className: `relative border border-[var(--appkit-color-border)] bg-[var(--appkit-color-surface)] overflow-hidden ${className}`, rounded: "xl", shadow: "sm-hover-md", children: [_jsx(DynamicBgDiv, { background: resolvedGradient, className: "absolute top-0 left-0 right-0 h-[3px]", "aria-hidden": "true" }), _jsxs(Row, { paddingX: "x-5", paddingY: "b-md-lg", padding: "t-lg", align: "start", justify: "between", gap: "3", children: [_jsxs(Div, { className: "min-w-0 flex-1", children: [_jsx(Text, { className: "text-[11px] tracking-widest text-[var(--appkit-color-text-muted)]", weight: "semibold", transform: "uppercase", children: label }), _jsx(Heading, { level: 3, className: "mt-2 tabular-nums leading-none text-[var(--appkit-color-text)]", size: "2xl", weight: "bold", children: value }), sub && (_jsx(Text, { className: "mt-1.5 text-[var(--appkit-color-text-muted)]", size: "xs", children: sub }))] }), icon && (_jsx(DynamicBgDiv, { background: resolvedGradient, className: "flex-shrink-0 w-10 h-10 flex items-center justify-center rounded-lg text-[length:var(--appkit-text-xl)]", children: icon }))] })] }));
+    /*
+     * 🛑 `!= null`, NOT a truthiness check. `trendPercent === 0` is a real
+     * measurement — "this figure did not move" — and `if (trendPercent)` would
+     * discard exactly that reading while keeping every other one. The same
+     * mistake as `rating !== undefined` passing for `rating: 0`, which showed
+     * five stars on unreviewed products (and is fixed two commits over).
+     */
+    const showTrend = trendPercent != null;
+    /* Two points minimum: one point is not a line, and a 1-point polyline
+     * renders as nothing at all rather than as a dot. */
+    const showSpark = Array.isArray(series) && series.length >= 2;
+    const up = showTrend && trendPercent > 0;
+    const down = showTrend && trendPercent < 0;
+    const flat = showTrend && trendPercent === 0;
+    /*
+     * 🛑 GOOD/BAD IS NOT UP/DOWN. Refunds, cancellations, failed payments and
+     * error counts all rise when things go wrong, so `higherIsBetter` decides
+     * the colour and the arrow only decides the direction. Tying the tone to
+     * the arrow would paint a spike in refunds green.
+     */
+    const good = higherIsBetter ? up : down;
+    const bad = higherIsBetter ? down : up;
+    const trendTone = flat ? "muted" : good ? "success" : bad ? "error" : "muted";
+    const trendArrow = flat ? "–" : up ? "▲" : "▼";
+    const trendText = flat
+        ? "no change"
+        : `${up ? "up" : "down"} ${Math.abs(trendPercent).toFixed(1).replace(/\.0$/, "")}%`;
+    // The sparkline's colour follows the same good/bad rule, not its slope.
+    const sparkRising = good || (flat && higherIsBetter);
+    return (_jsxs(Div, { className: `relative border border-[var(--appkit-color-border)] bg-[var(--appkit-color-surface)] overflow-hidden ${className}`, rounded: "xl", shadow: "sm-hover-md", children: [_jsx(DynamicBgDiv, { background: resolvedGradient, className: "absolute top-0 left-0 right-0 h-[3px]", "aria-hidden": "true" }), _jsxs(Row, { paddingX: "x-5", paddingY: "b-md-lg", padding: "t-lg", align: "start", justify: "between", gap: "3", children: [_jsxs(Div, { className: "min-w-0 flex-1", children: [_jsx(Text, { className: "text-[11px] tracking-widest text-[var(--appkit-color-text-muted)]", weight: "semibold", transform: "uppercase", children: label }), _jsx(Heading, { level: 3, className: "mt-2 tabular-nums leading-none text-[var(--appkit-color-text)]", size: "2xl", weight: "bold", children: value }), sub && (_jsx(Text, { className: "mt-1.5 text-[var(--appkit-color-text-muted)]", size: "xs", children: sub }))] }), icon && (_jsx(DynamicBgDiv, { background: resolvedGradient, className: "flex-shrink-0 w-10 h-10 flex items-center justify-center rounded-lg text-[length:var(--appkit-text-xl)]", children: icon }))] }), (showTrend || showSpark) && (_jsxs(Row, { paddingX: "x-5", padding: "b-md", align: "center", justify: "between", gap: "3", children: [showTrend ? (_jsxs(Text, { size: "xs", color: trendTone, weight: "semibold", children: [_jsxs("span", { "aria-hidden": "true", children: [trendArrow, " "] }), trendText, trendLabel ? (_jsxs(Text, { as: "span", size: "xs", color: "muted", weight: "normal", children: [" ", trendLabel] })) : null] })) : (_jsx("span", {})), showSpark && (
+                    /*
+                      🛑 `aria-hidden`, with NO accessible label. A sparkline is a
+                      decorative restatement of a trend already given in words
+                      directly beside it — describing it again would make a screen
+                      reader read the same fact twice. If the series ever carried
+                      information the trend line does not, it needs a real chart with
+                      a real description, not a label bolted onto 40 pixels.
+                    */
+                    _jsx(Div, { "aria-hidden": "true", className: "h-6 w-20 flex-shrink-0 opacity-80", children: _jsx(Sparkline, { series: series, rising: sparkRising }) }))] }))] }));
 }

package/dist/features/admin/components/index.d.ts

@@ -105,6 +105,10 @@ export { AdminPayoutMarkPaidModal } from "./AdminPayoutMarkPaidModal";
 export type { AdminPayoutMarkPaidModalProps } from "./AdminPayoutMarkPaidModal";
 export { AdminAuditLogView } from "./AdminAuditLogView";
 export type { AdminAuditLogViewProps } from "./AdminAuditLogView";
+export { AdminMoneyCasesView } from "./AdminMoneyCasesView";
+export type { AdminMoneyCasesViewProps } from "./AdminMoneyCasesView";
+export { AdminGatewayEventsView } from "./AdminGatewayEventsView";
+export type { AdminGatewayEventsViewProps } from "./AdminGatewayEventsView";
 export { ViewAuditLogEntryModal } from "./ViewAuditLogEntryModal";
 export type { AuditLogEntryDetail, ViewAuditLogEntryModalProps } from "./ViewAuditLogEntryModal";
 export { ViewNotificationModal } from "./ViewNotificationModal";

package/dist/features/admin/components/index.js

@@ -57,6 +57,12 @@ export { AdminHistoryView } from "./AdminHistoryView.js";
 export { AdminPayoutsView } from "./AdminPayoutsView.js";
 export { AdminPayoutMarkPaidModal } from "./AdminPayoutMarkPaidModal.js";
 export { AdminAuditLogView } from "./AdminAuditLogView.js";
+/*
+ * Payment protection — the operator queue for everything where money is at
+ * risk, and the first surface `paymentCases` has ever had.
+ */
+export { AdminMoneyCasesView } from "./AdminMoneyCasesView.js";
+export { AdminGatewayEventsView } from "./AdminGatewayEventsView.js";
 export { ViewAuditLogEntryModal } from "./ViewAuditLogEntryModal.js";
 export { ViewNotificationModal } from "./ViewNotificationModal.js";
 export { AdminReviewsView } from "./AdminReviewsView.js";

package/dist/features/admin/constants/filter-tabs.d.ts

@@ -699,3 +699,159 @@ export declare const SELLER_BID_STATUS_TABS: readonly [{
     readonly id: "cancelled";
     readonly label: "Cancelled";
 }];
+/** Admin > Money cases — `PaymentCaseStatus`. `open` is the birth state. */
+export declare const ADMIN_PAYMENT_CASE_STATUS_TABS: readonly [{
+    readonly id: "All";
+    readonly label: "All";
+}, {
+    readonly id: "open";
+    readonly label: "Open";
+}, {
+    readonly id: "under-review";
+    readonly label: "Under review";
+}, {
+    readonly id: "actioned";
+    readonly label: "Actioned";
+}, {
+    readonly id: "dismissed";
+    readonly label: "Dismissed";
+}];
+/**
+ * Admin > Money cases — `PaymentCaseKind`, all eleven.
+ *
+ * Labels are what an operator recognises, not the field value: `missing_order`
+ * reads as "Captured, no order", which is what the problem IS. The ids stay
+ * byte-exact against the union because they go straight into a Sieve equality
+ * and a near-miss returns zero rows forever with no error (Root Cause #33).
+ */
+export declare const ADMIN_PAYMENT_CASE_KIND_TABS: readonly [{
+    readonly id: "All";
+    readonly label: "All";
+}, {
+    readonly id: "missing_order";
+    readonly label: "Captured, no order";
+}, {
+    readonly id: "dispute";
+    readonly label: "Chargeback";
+}, {
+    readonly id: "manual_refund_due";
+    readonly label: "Refund owed";
+}, {
+    readonly id: "refund_mismatch";
+    readonly label: "Refund mismatch";
+}, {
+    readonly id: "amount_mismatch";
+    readonly label: "Amount mismatch";
+}, {
+    readonly id: "unprocessed_event";
+    readonly label: "Unprocessed event";
+}, {
+    readonly id: "status_conflict";
+    readonly label: "Status conflict";
+}, {
+    readonly id: "protection_claim";
+    readonly label: "Protection claim";
+}, {
+    readonly id: "grievance";
+    readonly label: "Grievance";
+}, {
+    readonly id: "shipping_unpriced";
+    readonly label: "Shipping unpriced";
+}, {
+    readonly id: "dead_job";
+    readonly label: "Dead job";
+}, {
+    readonly id: "ledger_drift";
+    readonly label: "Points drift";
+}];
+/** Admin > Money cases — `PaymentCaseSeverity`. Escalate-only, never downgraded. */
+export declare const ADMIN_PAYMENT_CASE_SEVERITY_TABS: readonly [{
+    readonly id: "All";
+    readonly label: "All";
+}, {
+    readonly id: "error";
+    readonly label: "Error";
+}, {
+    readonly id: "warning";
+    readonly label: "Warning";
+}, {
+    readonly id: "info";
+    readonly label: "Info";
+}];
+/**
+ * Admin > Gateway events — `GatewayEventStatus`.
+ *
+ * `ignored` is a real, healthy outcome and not a failure: an event type we are
+ * subscribed to but do not implement is recorded verbatim and settled
+ * `ignored`, which is the whole reason the inbox records unknown events rather
+ * than dropping them. `conflict` means a late event would have regressed an
+ * order's status — also not an error.
+ */
+export declare const ADMIN_GATEWAY_EVENT_STATUS_TABS: readonly [{
+    readonly id: "All";
+    readonly label: "All";
+}, {
+    readonly id: "received";
+    readonly label: "Received";
+}, {
+    readonly id: "processing";
+    readonly label: "Processing";
+}, {
+    readonly id: "processed";
+    readonly label: "Processed";
+}, {
+    readonly id: "failed";
+    readonly label: "Failed";
+}, {
+    readonly id: "conflict";
+    readonly label: "Late / conflict";
+}, {
+    readonly id: "ignored";
+    readonly label: "Ignored";
+}];
+/** Admin > Gateway events — `GatewayEventKind`. */
+export declare const ADMIN_GATEWAY_EVENT_KIND_TABS: readonly [{
+    readonly id: "All";
+    readonly label: "All";
+}, {
+    readonly id: "paid";
+    readonly label: "Paid";
+}, {
+    readonly id: "failed";
+    readonly label: "Failed";
+}, {
+    readonly id: "refund";
+    readonly label: "Refund";
+}, {
+    readonly id: "dispute";
+    readonly label: "Dispute";
+}, {
+    readonly id: "other";
+    readonly label: "Other";
+}];
+/** Admin > Protection claims — `ProtectionClaimStatus`. */
+export declare const ADMIN_PROTECTION_CLAIM_STATUS_TABS: readonly [{
+    readonly id: "All";
+    readonly label: "All";
+}, {
+    readonly id: "open";
+    readonly label: "Open";
+}, {
+    readonly id: "awaiting-return";
+    readonly label: "Awaiting return";
+}, {
+    readonly id: "inspecting";
+    readonly label: "Inspecting";
+}, {
+    readonly id: "upheld";
+    readonly label: "Upheld";
+}, {
+    readonly id: "rejected";
+    readonly label: "Rejected";
+}, {
+    readonly id: "withdrawn";
+    readonly label: "Withdrawn";
+}, {
+    readonly id: "expired";
+    readonly label: "Expired";
+}];

package/dist/features/admin/constants/filter-tabs.js

@@ -401,3 +401,109 @@ export const SELLER_BID_STATUS_TABS = [
     { id: "lost", label: "Lost" },
     { id: "cancelled", label: "Cancelled" },
 ];
+// ============================================================================
+// PAYMENT PROTECTION — the four collections the money spine writes to
+//
+// All eight arrays below are registered in `audit-filter-tab-enums`, whose
+// COVERAGE check is what makes them worth having: a kind with no chip is a kind
+// an operator cannot isolate, and these are the queues where that costs money
+// rather than convenience (Root Cause #72).
+//
+// They are rendered in a filter PANEL, not an always-visible chip row — eleven
+// case kinds and twelve obligation kinds are a complete set, not a scannable
+// one, and `renderFilterPanel` is where a complete set belongs.
+// ============================================================================
+/** Admin > Money cases — `PaymentCaseStatus`. `open` is the birth state. */
+export const ADMIN_PAYMENT_CASE_STATUS_TABS = [
+    ALL_TAB,
+    { id: "open", label: "Open" },
+    { id: "under-review", label: "Under review" },
+    { id: "actioned", label: "Actioned" },
+    { id: "dismissed", label: "Dismissed" },
+];
+/**
+ * Admin > Money cases — `PaymentCaseKind`, all eleven.
+ *
+ * Labels are what an operator recognises, not the field value: `missing_order`
+ * reads as "Captured, no order", which is what the problem IS. The ids stay
+ * byte-exact against the union because they go straight into a Sieve equality
+ * and a near-miss returns zero rows forever with no error (Root Cause #33).
+ */
+export const ADMIN_PAYMENT_CASE_KIND_TABS = [
+    ALL_TAB,
+    { id: "missing_order", label: "Captured, no order" },
+    { id: "dispute", label: "Chargeback" },
+    { id: "manual_refund_due", label: "Refund owed" },
+    { id: "refund_mismatch", label: "Refund mismatch" },
+    { id: "amount_mismatch", label: "Amount mismatch" },
+    { id: "unprocessed_event", label: "Unprocessed event" },
+    { id: "status_conflict", label: "Status conflict" },
+    { id: "protection_claim", label: "Protection claim" },
+    { id: "grievance", label: "Grievance" },
+    { id: "shipping_unpriced", label: "Shipping unpriced" },
+    { id: "dead_job", label: "Dead job" },
+    { id: "ledger_drift", label: "Points drift" },
+];
+/** Admin > Money cases — `PaymentCaseSeverity`. Escalate-only, never downgraded. */
+export const ADMIN_PAYMENT_CASE_SEVERITY_TABS = [
+    ALL_TAB,
+    { id: "error", label: "Error" },
+    { id: "warning", label: "Warning" },
+    { id: "info", label: "Info" },
+];
+/**
+ * Admin > Gateway events — `GatewayEventStatus`.
+ *
+ * `ignored` is a real, healthy outcome and not a failure: an event type we are
+ * subscribed to but do not implement is recorded verbatim and settled
+ * `ignored`, which is the whole reason the inbox records unknown events rather
+ * than dropping them. `conflict` means a late event would have regressed an
+ * order's status — also not an error.
+ */
+export const ADMIN_GATEWAY_EVENT_STATUS_TABS = [
+    ALL_TAB,
+    { id: "received", label: "Received" },
+    { id: "processing", label: "Processing" },
+    { id: "processed", label: "Processed" },
+    { id: "failed", label: "Failed" },
+    { id: "conflict", label: "Late / conflict" },
+    { id: "ignored", label: "Ignored" },
+];
+/** Admin > Gateway events — `GatewayEventKind`. */
+export const ADMIN_GATEWAY_EVENT_KIND_TABS = [
+    ALL_TAB,
+    { id: "paid", label: "Paid" },
+    { id: "failed", label: "Failed" },
+    { id: "refund", label: "Refund" },
+    { id: "dispute", label: "Dispute" },
+    { id: "other", label: "Other" },
+];
+/*
+ * 🛑 NO obligation tab arrays, and the absence is deliberate.
+ *
+ * `ADMIN_OBLIGATION_STATE_TABS` and `ADMIN_OBLIGATION_KIND_TABS` were written
+ * here and removed before shipping, because `/admin/maintenance/obligations`
+ * does not filter:
+ *
+ *   · the page reads `obligationsRepository.listDue()`, which returns OPEN and
+ *     overdue rows by definition — so a state filter would offer five chips of
+ *     which exactly one can ever match anything;
+ *   · `ObligationsRepository` declares **no `SIEVE_FIELDS`**, on its own stated
+ *     reasoning that a filterable surface nothing calls is the speculative-infra
+ *     pattern. Adding one to feed chips nobody needs would be that pattern
+ *     twice over.
+ *
+ * Twelve chips with nothing behind them is exactly the dead control this file's
+ * COVERAGE note exists to prevent — it would just fail in the other direction.
+ */
+/** Admin > Protection claims — `ProtectionClaimStatus`. */
+export const ADMIN_PROTECTION_CLAIM_STATUS_TABS = [
+    ALL_TAB,
+    { id: "open", label: "Open" },
+    { id: "awaiting-return", label: "Awaiting return" },
+    { id: "inspecting", label: "Inspecting" },
+    { id: "upheld", label: "Upheld" },
+    { id: "rejected", label: "Rejected" },
+    { id: "withdrawn", label: "Withdrawn" },
+    { id: "expired", label: "Expired" },
+];

package/dist/features/admin/repository/site-settings.repository.d.ts

@@ -5,6 +5,28 @@
  */
 import { BaseRepository } from "../../../providers/db-firebase";
 import { SiteSettingsDocument, SiteSettingsCredentialsMasked, SiteSettingsUpdateInput } from "../schemas";
+/**
+ * Flatten a nested update into Firestore dotted field paths, so a partial
+ * group update MERGES into the stored map instead of replacing it.
+ *
+ * `update({ commissions: { gstPercent: 18 } })` deletes every other key under
+ * `commissions`; `update({ "commissions.gstPercent": 18 })` touches one leaf.
+ * See the call site for the five keys that were silently destroyed by the
+ * former (D13).
+ *
+ * Three cases are deliberately NOT recursed into:
+ *
+ * · **Arrays** — an array is a VALUE, not a map. Flattening
+ *   `legalPages.sections.0.title` would make a shorter replacement array leave
+ *   the old tail in place, which is a worse bug than the one being fixed.
+ * · **`undefined`** — kept at its own path so a caller can still delete a
+ *   field. Recursing would turn it into a path to nothing.
+ * · **`Date` and any other class instance** — Firestore stores a `Date` as a
+ *   Timestamp; walking its properties would write `{}`. Tested by rejecting
+ *   anything whose prototype is not `Object.prototype`, which also covers
+ *   `FieldValue` sentinels and `Timestamp` itself.
+ */
+export declare function toDottedPaths(input: Record<string, unknown>, prefix?: string): Record<string, unknown>;
 /**
  * Repository for site settings management
  *

package/dist/features/admin/repository/site-settings.repository.js

@@ -17,6 +17,53 @@ import { cacheManager } from "../../../core/CacheManager.js";
 import { SITE_SETTINGS_COLLECTION, DEFAULT_SITE_SETTINGS_DATA, } from "../schemas/index.js";
 import { DatabaseError } from "../../../errors/index.js";
 import { decryptSecret, encryptSecret, maskSecret } from "../../../security/index.js";
+/**
+ * Flatten a nested update into Firestore dotted field paths, so a partial
+ * group update MERGES into the stored map instead of replacing it.
+ *
+ * `update({ commissions: { gstPercent: 18 } })` deletes every other key under
+ * `commissions`; `update({ "commissions.gstPercent": 18 })` touches one leaf.
+ * See the call site for the five keys that were silently destroyed by the
+ * former (D13).
+ *
+ * Three cases are deliberately NOT recursed into:
+ *
+ * · **Arrays** — an array is a VALUE, not a map. Flattening
+ *   `legalPages.sections.0.title` would make a shorter replacement array leave
+ *   the old tail in place, which is a worse bug than the one being fixed.
+ * · **`undefined`** — kept at its own path so a caller can still delete a
+ *   field. Recursing would turn it into a path to nothing.
+ * · **`Date` and any other class instance** — Firestore stores a `Date` as a
+ *   Timestamp; walking its properties would write `{}`. Tested by rejecting
+ *   anything whose prototype is not `Object.prototype`, which also covers
+ *   `FieldValue` sentinels and `Timestamp` itself.
+ */
+export function toDottedPaths(input, prefix = "") {
+    const out = {};
+    for (const [key, value] of Object.entries(input)) {
+        const path = prefix ? `${prefix}.${key}` : key;
+        const isPlainObject = typeof value === "object" &&
+            value !== null &&
+            !Array.isArray(value) &&
+            Object.getPrototypeOf(value) === Object.prototype;
+        if (isPlainObject) {
+            const nested = toDottedPaths(value, path);
+            /*
+             * An EMPTY object is written at its own path rather than vanishing.
+             * `{ watermark: {} }` is a caller saying "clear this group"; dropping it
+             * because it produced no leaves would silently ignore the instruction.
+             */
+            if (Object.keys(nested).length === 0)
+                out[path] = value;
+            else
+                Object.assign(out, nested);
+        }
+        else {
+            out[path] = value;
+        }
+    }
+    return out;
+}
 /**
  * Repository for site settings management
  *
@@ -113,10 +160,44 @@ export class SiteSettingsRepository extends BaseRepository {
                 ...finalUpdates,
                 updatedAt: new Date(),
             });
+            /*
+             * ── D13: DOTTED PATHS, not a wholesale nested-map replace ────────────
+             *
+             * 🛑 This was `.update(updateData)` with nested objects, and Firestore's
+             * `update()` REPLACES a nested map wholesale rather than merging into
+             * it. So saving `{ commissions: { platformFeePercent: 2 } }` deleted
+             * every other key under `commissions`.
+             *
+             * That is not hypothetical. `AdminSiteSettingsView`'s commissions
+             * payload omitted FIVE keys — `saleProtectionFeeEnabled`,
+             * `saleProtectionFeePercent`, `saleProtectionFeeMin`,
+             * `codHandlingFeeCap`, `codHandlingFeePercent` — with no state, no field
+             * and no control for any of them. So the FIRST save of any commissions
+             * field silently:
+             *
+             *   · stopped sale protection being sold, a product we charge 3% (min
+             *     ₹49) for, with no error and nothing in the UI to notice; and
+             *   · reverted COD handling to code defaults.
+             *
+             * It also made CLAUDE.md's stated remediation — "enable them once at
+             * Admin → Site Settings → Commissions" — impossible, because there was
+             * no control there to enable them with.
+             *
+             * Flattening to dotted paths is the structural fix: `commissions.gstPercent`
+             * touches exactly that leaf. The alternative (adding the five missing
+             * fields to the form) fixes TODAY'S instance and leaves the next group
+             * that grows a field to hit the same wall — and `legalPages` had already
+             * hit it independently (D19), which is the evidence that this recurs.
+             *
+             * 🛑 ARRAYS AND `undefined` ARE NOT FLATTENED. An array is a value, not a
+             * map: flattening `legalPages.sections.0.title` would make a shorter
+             * replacement array leave the old tail behind. And `undefined` must stay
+             * a top-level delete rather than becoming a dotted path to nothing.
+             */
             await this.db
                 .collection(this.collection)
                 .doc(this.SINGLETON_ID)
-                .update(updateData);
+                .update(toDottedPaths(updateData));
             const latest = await this.getSingleton();
             cacheManager.set(this.cacheKey(), latest, {
                 ttl: SiteSettingsRepository.CACHE_TTL_MS,

package/dist/features/admin/schemas/admin-editor-forms.d.ts

@@ -92,6 +92,17 @@ export declare const brandFormSchema: z.ZodObject<{
     website: z.ZodUnion<[z.ZodOptional<z.ZodString>, z.ZodLiteral<"">]>;
     country: z.ZodUnion<[z.ZodOptional<z.ZodString>, z.ZodLiteral<"">]>;
     founded: z.ZodOptional<z.ZodNumber>;
+    highlightsText: z.ZodUnion<[z.ZodOptional<z.ZodString>, z.ZodLiteral<"">]>;
+    faqs: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        question: z.ZodString;
+        answer: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        question: string;
+        answer: string;
+    }, {
+        question: string;
+        answer: string;
+    }>, "many">>;
     isActive: z.ZodBoolean;
     displayOrder: z.ZodOptional<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
@@ -99,20 +110,30 @@ export declare const brandFormSchema: z.ZodObject<{
     isActive: boolean;
     country?: string | undefined;
     slug?: string | undefined;
+    faqs?: {
+        question: string;
+        answer: string;
+    }[] | undefined;
     description?: string | undefined;
     displayOrder?: number | undefined;
     logoURL?: string | undefined;
     website?: string | undefined;
     founded?: number | undefined;
+    highlightsText?: string | undefined;
 }, {
     name: string;
     isActive: boolean;
     country?: string | undefined;
     slug?: string | undefined;
+    faqs?: {
+        question: string;
+        answer: string;
+    }[] | undefined;
     description?: string | undefined;
     displayOrder?: number | undefined;
     logoURL?: string | undefined;
     website?: string | undefined;
     founded?: number | undefined;
+    highlightsText?: string | undefined;
 }>;
 export type BrandFormValues = z.infer<typeof brandFormSchema>;

package/dist/features/admin/schemas/admin-editor-forms.js

@@ -177,6 +177,50 @@ export const brandFormSchema = z.object({
         section: "identity", order: 2, row: "pair", label: "Country of origin",
     }),
     founded: annotate(z.number().int().min(1800, "That is earlier than any brand on record.").max(new Date().getFullYear(), "A founding year cannot be in the future.").optional(), { section: "identity", order: 3, row: "pair", kind: "number", label: "Founded year" }),
+    /*
+     * ── Editorial content ────────────────────────────────────────────────────
+     *
+     * 🛑 BOTH OF THESE HAVE RENDERED ON THE BRAND PAGE SINCE THEY SHIPPED, with
+     * no way to author them. `BrandDetailPageView:418` mounts
+     * `<CategoryHighlightsAndFaqSection highlights={brand?.highlights}
+     * faqs={brand?.faqs} />`, `CategoryDocument` declares both with a comment
+     * saying they render on "category and BRAND detail pages", and
+     * `CATEGORIES_UPDATABLE_FIELDS` has always permitted the write. The only
+     * missing piece was a form — the category editor had one, the brand editor
+     * did not, so brand highlights and FAQs were unreachable.
+     *
+     * `highlightsText` is a newline-separated textarea rather than a repeater,
+     * matching the category editor exactly: these are a flat `string[]`, an
+     * admin pasting five bullets wants to paste five lines, and order is
+     * preserved by the text itself.
+     */
+    highlightsText: annotate(z.string().optional().or(z.literal("")), {
+        section: "content", sectionLabel: "Content", order: 1, row: "full",
+        kind: "textarea", label: "Highlights — one per line",
+        help: "Short \"why shop this brand\" bullets, shown above the FAQs.",
+    }),
+    /*
+     * 🛑 DECLARED HERE SO THE PARSE COVERS IT, rendered by a custom `renderers`
+     * entry in the editor. `buildSectionsFromSchema` has no `kind` for a
+     * per-row shape, and inventing one for a single consumer would be the
+     * speculative-infra move — `logoURL` already establishes the pattern of a
+     * schema field with a bespoke renderer.
+     *
+     * It lives in the DRAFT rather than its own `useState`, unlike the category
+     * editor's three repeaters. Those predate this form being schema-driven;
+     * here the draft can hold the array, so validation, dirty-tracking and the
+     * error summary all see it, and there is one source of truth instead of two.
+     */
+    faqs: annotate(z
+        .array(z.object({
+        question: z.string().min(1, "A question is required").max(300),
+        answer: z.string().min(1, "An answer is required").max(2000),
+    }))
+        .max(8, "At most 8 questions")
+        .optional(), {
+        section: "content", order: 2, row: "full", label: "Brand FAQs",
+        help: "Rendered beneath the highlights on the brand page.",
+    }),
     isActive: annotate(z.boolean(), {
         section: "visibility", sectionLabel: "Visibility", order: 1, row: "quarter",
         label: "Active",

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

@@ -292,7 +292,11 @@ export const DEFAULT_SITE_SETTINGS_DATA = {
         platformShippingPercent: 10,
         platformShippingFixedMin: 0,
         autoPayoutWindowDays: 7,
-        payoutHoldDays: 2,
+        // 7, not 2 — see `PAYOUT_HOLD_FLOOR_DAYS`. A 2-day hold releases the
+        // seller's money inside both the 7-day return window and the 7-day
+        // sale-protection claim window, so it was never a legal value; it was
+        // merely an unread one (D28).
+        payoutHoldDays: 7,
         minPayoutAmount: 100,
         auctionListingFee: 0,
         preOrderListingFee: 0,