@mohasinac/appkit 4.13.1 → 4.15.0

package/dist/features/admin/components/sections/adminSectionsTypes.js

@@ -1,32 +1,50 @@
 import { ROUTES } from "../../../../next/routing/route-map";
 const LABEL_VERIFIED_SELLERS = "Verified Sellers";
-export const SECTION_TYPE_OPTIONS = [
-    "welcome",
-    "stats",
-    "trust-indicators",
-    "categories",
-    "brands",
-    "products",
-    "pre-orders",
-    "auctions",
-    "banner",
-    "features",
-    "reviews",
-    "whatsapp-community",
-    "faq",
-    "blog-articles",
-    "newsletter",
-    "stores",
-    "events",
-    "social-feed",
-    "carousel",
-    "custom-cards",
-    "google-reviews",
-    "featured-bundles",
-    "prize-draws",
-    "event-raffles",
-    "collection-cards",
-];
+/*
+ * The admin dropdown's section types.
+ *
+ * 🛑 This used to be a bare `as const` array with its OWN `SectionType` derived
+ * from it — a second declaration shadowing the real `SectionType` in
+ * `features/homepage/schemas/firestore.ts`, which is how the two came to
+ * disagree with the create route (Recurrent Root Cause #36's shape, one union
+ * over). The route's own copy was missing `featured-bundles`, `prize-draws`,
+ * `event-raffles` and `collection-cards`, so choosing any of those four in this
+ * dropdown produced a 400 on save — four of twenty-five section types could be
+ * configured in full and never created.
+ *
+ * It is now a `Record<CanonicalSectionType, true>`, so a type added to the
+ * union and not offered here is a COMPILE error, and an entry here that is not
+ * a real section type is too. Declaration order is preserved because the array
+ * is derived from this map's keys, and that order is the dropdown's order.
+ */
+const SECTION_TYPE_PRESENCE = {
+    welcome: true,
+    stats: true,
+    "trust-indicators": true,
+    categories: true,
+    brands: true,
+    products: true,
+    "pre-orders": true,
+    auctions: true,
+    banner: true,
+    features: true,
+    reviews: true,
+    "whatsapp-community": true,
+    faq: true,
+    "blog-articles": true,
+    newsletter: true,
+    stores: true,
+    events: true,
+    "social-feed": true,
+    carousel: true,
+    "custom-cards": true,
+    "google-reviews": true,
+    "featured-bundles": true,
+    "prize-draws": true,
+    "event-raffles": true,
+    "collection-cards": true,
+};
+export const SECTION_TYPE_OPTIONS = Object.keys(SECTION_TYPE_PRESENCE);
 export const DEFAULT_PRODUCTS_BUILDER = {
     title: "Featured Products",
     subtitle: "",

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

@@ -188,6 +188,9 @@ export declare const ADMIN_AUDIT_LOG_ACTION_TABS: readonly [{
 }, {
     readonly id: "payout_mark_paid";
     readonly label: "Payout paid";
+}, {
+    readonly id: "offer_cancel";
+    readonly label: "Offer cancelled";
 }, {
     readonly id: "store_status_change";
     readonly label: "Store status";
@@ -203,6 +206,9 @@ export declare const ADMIN_ORDER_STATUS_TABS: readonly [{
 }, {
     readonly id: "pending";
     readonly label: "Pending";
+}, {
+    readonly id: "confirmed";
+    readonly label: "Confirmed";
 }, {
     readonly id: "processing";
     readonly label: "Processing";
@@ -221,6 +227,9 @@ export declare const ADMIN_ORDER_STATUS_TABS: readonly [{
 }, {
     readonly id: "return_requested";
     readonly label: "Return Requested";
+}, {
+    readonly id: "returned";
+    readonly label: "Returned";
 }];
 /**
  * Admin > Orders — manual-payment (cash / UPI / EMI) review queue.
@@ -338,6 +347,12 @@ export declare const ADMIN_EVENT_ENTRY_STATUS_TABS: readonly [{
  *  feature's own events/types/index.ts). A "Published" chip previously
  *  returned zero rows every time — removed rather than aliased since
  *  "Active" already covers the intended meaning. */
+/**
+ * Every `EventStatus`, not a subset. `paused` and `cancelled` were missing
+ * until 2026-08-24 — a real status with no chip is unreachable, and
+ * `audit-filter-tab-enums` never caught it because that audit only checks the
+ * reverse (that no chip names a DEAD value).
+ */
 export declare const ADMIN_EVENT_STATUS_TABS: readonly [{
     readonly id: "All";
     readonly label: "All";
@@ -347,9 +362,15 @@ export declare const ADMIN_EVENT_STATUS_TABS: readonly [{
 }, {
     readonly id: "active";
     readonly label: "Active";
+}, {
+    readonly id: "paused";
+    readonly label: "Paused";
 }, {
     readonly id: "ended";
     readonly label: "Ended";
+}, {
+    readonly id: "cancelled";
+    readonly label: "Cancelled";
 }];
 /** Admin > Scammers — scammer profile status filter chip set. */
 export declare const ADMIN_SCAMMER_STATUS_TABS: readonly [{
@@ -460,6 +481,9 @@ export declare const SELLER_PRODUCT_STATUS_TABS: readonly [{
 }, {
     readonly id: "archived";
     readonly label: "Archived";
+}, {
+    readonly id: "in_review";
+    readonly label: "In Review";
 }];
 /** Seller > Auctions — auction-state filter chip set. Real `ProductStatus`
  *  has no "active"/"ended"/"cancelled" values. "Active" fixed to
@@ -480,6 +504,12 @@ export declare const SELLER_AUCTION_STATUS_TABS: readonly [{
 }, {
     readonly id: "draft";
     readonly label: "Draft";
+}, {
+    readonly id: "in_review";
+    readonly label: "In Review";
+}, {
+    readonly id: "archived";
+    readonly label: "Archived";
 }];
 /** Seller > Pre-orders — pre-order-state filter chip set. Same root cause
  *  and fix as SELLER_AUCTION_STATUS_TABS above — no "active"/"cancelled"
@@ -497,6 +527,9 @@ export declare const SELLER_PRE_ORDER_STATUS_TABS: readonly [{
 }, {
     readonly id: "archived";
     readonly label: "Archived";
+}, {
+    readonly id: "in_review";
+    readonly label: "In Review";
 }];
 /** Seller > Prize Draws — draw-state filter chip set. Same root cause and
  *  fix as SELLER_AUCTION_STATUS_TABS — "ended" is derived from
@@ -511,6 +544,12 @@ export declare const SELLER_PRIZE_DRAW_STATUS_TABS: readonly [{
 }, {
     readonly id: "draft";
     readonly label: "Draft";
+}, {
+    readonly id: "in_review";
+    readonly label: "In Review";
+}, {
+    readonly id: "archived";
+    readonly label: "Archived";
 }];
 /** Seller > Orders — order-state filter chip set. Subset of
  *  `ADMIN_ORDER_STATUS_TABS` — sellers don't see `RETURN_REQUESTED` until
@@ -524,6 +563,9 @@ export declare const SELLER_ORDER_STATUS_TABS: readonly [{
 }, {
     readonly id: "pending";
     readonly label: "Pending";
+}, {
+    readonly id: "confirmed";
+    readonly label: "Confirmed";
 }, {
     readonly id: "processing";
     readonly label: "Processing";
@@ -539,6 +581,44 @@ export declare const SELLER_ORDER_STATUS_TABS: readonly [{
 }, {
     readonly id: "refunded";
     readonly label: "Refunded";
+}, {
+    readonly id: "return_requested";
+    readonly label: "Return Requested";
+}, {
+    readonly id: "returned";
+    readonly label: "Returned";
+}];
+/**
+ * Admin > Offers — the FULL `OfferStatus` union, unlike the seller variant
+ * below, which deliberately surfaces only the four states a seller acts on.
+ * An admin is auditing the whole lifecycle, so `countered`, `withdrawn` and
+ * `paid` all need to be reachable. Cross-checked against the real union by
+ * `audit-filter-tab-enums`.
+ */
+export declare const ADMIN_OFFER_STATUS_TABS: readonly [{
+    readonly id: "All";
+    readonly label: "All";
+}, {
+    readonly id: "pending";
+    readonly label: "Pending";
+}, {
+    readonly id: "countered";
+    readonly label: "Countered";
+}, {
+    readonly id: "accepted";
+    readonly label: "Accepted";
+}, {
+    readonly id: "paid";
+    readonly label: "Paid";
+}, {
+    readonly id: "declined";
+    readonly label: "Declined";
+}, {
+    readonly id: "expired";
+    readonly label: "Expired";
+}, {
+    readonly id: "withdrawn";
+    readonly label: "Withdrawn";
 }];
 /** Seller > Offers — offer-state filter chip set. Real `OfferStatus` is
  *  pending|accepted|declined|countered|expired|withdrawn|paid — there is no
@@ -560,6 +640,15 @@ export declare const SELLER_OFFER_STATUS_TABS: readonly [{
 }, {
     readonly id: "expired";
     readonly label: "Expired";
+}, {
+    readonly id: "countered";
+    readonly label: "Countered";
+}, {
+    readonly id: "withdrawn";
+    readonly label: "Withdrawn";
+}, {
+    readonly id: "paid";
+    readonly label: "Paid";
 }];
 /** Seller > Bids — bid-state filter chip set. Uses the empty-sentinel
  *  variant (see `EMPTY_TAB`). */

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

@@ -10,6 +10,14 @@
  * primitive and stay in sync when statuses are added.
  */
 export const ALL_TAB = { id: "All", label: "All" };
+// COVERAGE (2026-08-24): `audit-filter-tab-enums` gained a check that every
+// value of the backing enum HAS a chip, not just that every chip is a real
+// value. It immediately found ten gaps across the seller sets — `in_review`
+// (where a submission waits on admin approval, arguably the state a seller most
+// wants to filter for), `archived`, `returned`, and the offer states
+// `countered` / `withdrawn` / `paid`. Rows in those states were visible under
+// "All" and isolatable by nothing. All ten now have chips; anything genuinely
+// not worth a chip goes in that audit entry's `omit` list with a reason.
 /** Admin > Products — listing status filter chip set. Real `ProductStatus`
  *  is draft|published|in_review|archived — "pending" fixed to "in_review"
  *  (its real meaning); the previous id never matched any document. */
@@ -97,6 +105,7 @@ export const ADMIN_AUDIT_LOG_ACTION_TABS = [
     { id: "checkout_bypass", label: "Checkout bypass" },
     { id: "coupon_update", label: "Coupon update" },
     { id: "payout_mark_paid", label: "Payout paid" },
+    { id: "offer_cancel", label: "Offer cancelled" },
     { id: "store_status_change", label: "Store status" },
     { id: "user_role_change", label: "Role change" },
 ];
@@ -105,12 +114,17 @@ export const ADMIN_AUDIT_LOG_ACTION_TABS = [
 export const ADMIN_ORDER_STATUS_TABS = [
     ALL_TAB,
     { id: "pending", label: "Pending" },
+    // `confirmed` and `returned` were both missing until 2026-08-24 even though
+    // both are real `OrderStatusValues` an order reaches — so an admin could see
+    // such an order in the All tab and had no chip that would isolate it.
+    { id: "confirmed", label: "Confirmed" },
     { id: "processing", label: "Processing" },
     { id: "shipped", label: "Shipped" },
     { id: "delivered", label: "Delivered" },
     { id: "cancelled", label: "Cancelled" },
     { id: "refunded", label: "Refunded" },
     { id: "return_requested", label: "Return Requested" },
+    { id: "returned", label: "Returned" },
 ];
 /**
  * Admin > Orders — manual-payment (cash / UPI / EMI) review queue.
@@ -177,11 +191,19 @@ export const ADMIN_EVENT_ENTRY_STATUS_TABS = [
  *  feature's own events/types/index.ts). A "Published" chip previously
  *  returned zero rows every time — removed rather than aliased since
  *  "Active" already covers the intended meaning. */
+/**
+ * Every `EventStatus`, not a subset. `paused` and `cancelled` were missing
+ * until 2026-08-24 — a real status with no chip is unreachable, and
+ * `audit-filter-tab-enums` never caught it because that audit only checks the
+ * reverse (that no chip names a DEAD value).
+ */
 export const ADMIN_EVENT_STATUS_TABS = [
     ALL_TAB,
     { id: "draft", label: "Draft" },
     { id: "active", label: "Active" },
+    { id: "paused", label: "Paused" },
     { id: "ended", label: "Ended" },
+    { id: "cancelled", label: "Cancelled" },
 ];
 /** Admin > Scammers — scammer profile status filter chip set. */
 export const ADMIN_SCAMMER_STATUS_TABS = [
@@ -242,6 +264,7 @@ export const SELLER_PRODUCT_STATUS_TABS = [
     { id: "published", label: "Active" },
     { id: "draft", label: "Draft" },
     { id: "archived", label: "Archived" },
+    { id: "in_review", label: "In Review" },
 ];
 /** Seller > Auctions — auction-state filter chip set. Real `ProductStatus`
  *  has no "active"/"ended"/"cancelled" values. "Active" fixed to
@@ -257,6 +280,8 @@ export const SELLER_AUCTION_STATUS_TABS = [
     ALL_TAB,
     { id: "published", label: "Active" },
     { id: "draft", label: "Draft" },
+    { id: "in_review", label: "In Review" },
+    { id: "archived", label: "Archived" },
 ];
 /** Seller > Pre-orders — pre-order-state filter chip set. Same root cause
  *  and fix as SELLER_AUCTION_STATUS_TABS above — no "active"/"cancelled"
@@ -267,6 +292,7 @@ export const SELLER_PRE_ORDER_STATUS_TABS = [
     { id: "published", label: "Active" },
     { id: "draft", label: "Draft" },
     { id: "archived", label: "Archived" },
+    { id: "in_review", label: "In Review" },
 ];
 /** Seller > Prize Draws — draw-state filter chip set. Same root cause and
  *  fix as SELLER_AUCTION_STATUS_TABS — "ended" is derived from
@@ -276,6 +302,8 @@ export const SELLER_PRIZE_DRAW_STATUS_TABS = [
     ALL_TAB,
     { id: "published", label: "Active" },
     { id: "draft", label: "Draft" },
+    { id: "in_review", label: "In Review" },
+    { id: "archived", label: "Archived" },
 ];
 /** Seller > Orders — order-state filter chip set. Subset of
  *  `ADMIN_ORDER_STATUS_TABS` — sellers don't see `RETURN_REQUESTED` until
@@ -286,11 +314,36 @@ export const SELLER_PRIZE_DRAW_STATUS_TABS = [
 export const SELLER_ORDER_STATUS_TABS = [
     ALL_TAB,
     { id: "pending", label: "Pending" },
+    // `confirmed` is settable from SellerOrdersView's own Update-Status dropdown
+    // but had no chip here, so a seller could move an order into a state they
+    // could then never filter for. `return_requested` was excluded on the theory
+    // that sellers never see one — they do, it is the state a buyer's return
+    // request lands in and the seller is the one who has to act on it.
+    { id: "confirmed", label: "Confirmed" },
     { id: "processing", label: "Processing" },
     { id: "shipped", label: "Shipped" },
     { id: "delivered", label: "Delivered" },
     { id: "cancelled", label: "Cancelled" },
     { id: "refunded", label: "Refunded" },
+    { id: "return_requested", label: "Return Requested" },
+    { id: "returned", label: "Returned" },
+];
+/**
+ * Admin > Offers — the FULL `OfferStatus` union, unlike the seller variant
+ * below, which deliberately surfaces only the four states a seller acts on.
+ * An admin is auditing the whole lifecycle, so `countered`, `withdrawn` and
+ * `paid` all need to be reachable. Cross-checked against the real union by
+ * `audit-filter-tab-enums`.
+ */
+export const ADMIN_OFFER_STATUS_TABS = [
+    ALL_TAB,
+    { id: "pending", label: "Pending" },
+    { id: "countered", label: "Countered" },
+    { id: "accepted", label: "Accepted" },
+    { id: "paid", label: "Paid" },
+    { id: "declined", label: "Declined" },
+    { id: "expired", label: "Expired" },
+    { id: "withdrawn", label: "Withdrawn" },
 ];
 /** Seller > Offers — offer-state filter chip set. Real `OfferStatus` is
  *  pending|accepted|declined|countered|expired|withdrawn|paid — there is no
@@ -303,6 +356,9 @@ export const SELLER_OFFER_STATUS_TABS = [
     { id: "accepted", label: "Accepted" },
     { id: "declined", label: "Rejected" },
     { id: "expired", label: "Expired" },
+    { id: "countered", label: "Countered" },
+    { id: "withdrawn", label: "Withdrawn" },
+    { id: "paid", label: "Paid" },
 ];
 /** Seller > Bids — bid-state filter chip set. Uses the empty-sentinel
  *  variant (see `EMPTY_TAB`). */

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

@@ -275,15 +275,82 @@ export interface SiteSettingsTheme {
     /** Theme id applied when the user's resolved mode is `"dark"`. */
     defaultDarkThemeId?: string;
 }
+/** Third-party analytics/tag IDs. Public by nature — they ship in page markup. */
+export interface SiteSettingsIntegrations {
+    googleAnalyticsId?: string;
+    facebookPixelId?: string;
+    gtmContainerId?: string;
+}
+/** Admin-tunable platform caps. Enforced server-side; not buyer-facing. */
+export interface SiteSettingsPlatformLimits {
+    maxProductsPerStore?: number;
+    maxImagesPerProduct?: number;
+    maxVideoSizeMb?: number;
+    maxCustomFieldsPerProduct?: number;
+    maxCustomSectionsPerProduct?: number;
+    orderCancellationWindowHours?: number;
+}
+/** Embedded in siteSettings.adSettings — a type alias, not a collection root. */
+export type SiteSettingsAdPlacement = {
+    id: string;
+    label: string;
+    enabled: boolean;
+    reservedHeight: number;
+};
+/** Embedded in siteSettings.adSettings — a type alias, not a collection root. */
+export type SiteSettingsAdInventoryItem = {
+    id: string;
+    name: string;
+    provider: "manual" | "adsense" | "thirdParty";
+    status: "draft" | "active" | "scheduled" | "paused";
+    placementIds: string[];
+    requiresConsent: boolean;
+    priority: number;
+    startAt?: string;
+    endAt?: string;
+    createdAt: string;
+    updatedAt: string;
+    updatedBy: string;
+    creative: {
+        title?: string;
+        body?: string;
+        imageUrl?: string;
+        ctaLabel?: string;
+        ctaHref?: string;
+        adsenseSlot?: string;
+        thirdPartyUrl?: string;
+    };
+};
+/**
+ * Ad inventory + provider config.
+ *
+ * `providerCredentials` is masked by `GET /api/admin/ads` and must never be
+ * returned by a public endpoint; `inventory` holds draft/paused/scheduled
+ * entries that `GET /api/ads` deliberately filters out. Both are therefore in
+ * `PRIVATE_SITE_SETTINGS_FIELDS` — the whole group is server-side only.
+ */
+export interface SiteSettingsAdSettings {
+    consentRequired: boolean;
+    placements: readonly SiteSettingsAdPlacement[];
+    providerCredentials: {
+        adsenseClientId: string;
+        thirdPartyScriptUrl: string;
+    };
+    inventory: SiteSettingsAdInventoryItem[];
+}
 export interface SiteSettingsDocument extends BaseDocument {
     id: "global";
     siteName: string;
+    /** Short strapline shown beside the site name in admin chrome. */
+    tagline?: string;
     motto: string;
     logo: {
         url: string;
         alt: string;
         format: "svg" | "png";
     };
+    /** Favicon URL. Distinct from `logo.url`, which is the wordmark. */
+    favicon?: string;
     background: {
         light: {
             type: "color" | "gradient" | "image" | "video";
@@ -452,6 +519,19 @@ export interface SiteSettingsDocument extends BaseDocument {
         notifications: boolean;
         sellerRegistration: boolean;
         preOrders: boolean;
+        /**
+         * Buyer price negotiation (Make an Offer / counter-offer).
+         *
+         * The global kill switch. Per-listing opt-in still applies on top of it via
+         * `ProductDocument.allowOffers`, and only certain listing types support
+         * offers at all (`LISTING_TYPE_CAPABILITIES.canMakeOffer`) — a product needs
+         * all three to show the CTA.
+         *
+         * Guards NEW offers only. Switching it off must not strand in-flight ones:
+         * sellers keep responding, buyers keep checking out accepted offers, and
+         * both dashboards stay reachable.
+         */
+        offers: boolean;
         /** When true, admin users see a bypass button in checkout that skips OTP and payment. Server-enforced. */
         adminCheckoutBypass?: boolean;
         listingTypes?: {
@@ -471,11 +551,26 @@ export interface SiteSettingsDocument extends BaseDocument {
             bundle?: boolean;
         };
     };
+    /**
+     * Admin-authored HTML overrides for the public policy pages. When a key holds
+     * a non-empty string, `PolicyPageView` renders it instead of the i18n
+     * `sections[]` fallback for that page.
+     *
+     * These key names are load-bearing — they must match `POLICY_META[*].firestoreField`
+     * in `features/about/components/PolicyPageView.tsx` (read side) and the
+     * `legalPages` payload built by `AdminSiteSettingsView` (write side). Until
+     * 2026-08-24 this type declared `termsOfService`/`privacyPolicy`/`shippingPolicy`,
+     * three names that neither side ever used; the read path went through an
+     * `as any` cast, so `tsc` never caught the drift (Root Cause #38 family).
+     */
     legalPages: {
-        termsOfService: string;
-        privacyPolicy: string;
+        terms: string;
+        privacy: string;
+        cookies: string;
         refundPolicy: string;
-        shippingPolicy: string;
+        shipping: string;
+        ethics: string;
+        codeOfConduct: string;
     };
     shipping: {
         estimatedDays: number;
@@ -508,9 +603,21 @@ export interface SiteSettingsDocument extends BaseDocument {
         };
         newsletterEnabled?: boolean;
     };
+    /**
+     * `message` is canonical — it is what `AnnouncementBar` and the homepage
+     * read. `AdminSiteSettingsView` used to write the text under a `text` key
+     * instead, so anything typed in the main Site Settings editor was saved and
+     * never displayed; `link`/`backgroundColor` were collected and had no
+     * renderer at all. Unified on `message` 2026-08-24 (migration
+     * `scripts/migrate-settings-wiring.mjs` copies any stray `text` across).
+     */
     announcementBar?: {
         enabled: boolean;
         message: string;
+        /** Optional destination — renders the message as a link. */
+        link?: string;
+        /** Optional CSS colour override for the bar background. */
+        backgroundColor?: string;
     };
     /**
      * Image watermark configuration applied by the `/api/media/[...slug]` CDN
@@ -544,6 +651,18 @@ export interface SiteSettingsDocument extends BaseDocument {
     };
     /** Encrypted provider credentials � never return raw to the client. */
     credentials?: SiteSettingsCredentials;
+    /**
+     * These three were written by `AdminSiteSettingsView.buildFullPayload()` and
+     * read back by it, but were never declared here. Being absent from the type
+     * meant no type-driven check could see them — and the public site-settings
+     * deny-list, which strips named fields off a spread, shipped all three to
+     * anonymous callers by default (`adSettings.providerCredentials` unmasked,
+     * plus every draft/paused ad). Declared 2026-08-24 so they are visible to
+     * `audit-public-projection-parity`.
+     */
+    integrations?: SiteSettingsIntegrations;
+    platformLimits?: SiteSettingsPlatformLimits;
+    adSettings?: SiteSettingsAdSettings;
     /**
      * Theme color overrides — injected as CSS custom properties by LayoutShellClient.
      * Keys map to --appkit-color-* variables (e.g. primary → --appkit-color-primary).

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

@@ -241,6 +241,7 @@ export const DEFAULT_SITE_SETTINGS_DATA = {
         notifications: true,
         sellerRegistration: true,
         preOrders: true,
+        offers: true,
         // W1-37 2026-05-23 — Phase 2 listing types enabled by default; all per-type
         // surfaces (seller + admin via W1-29 + public) are now shipped.
         listingTypes: {

package/dist/features/admin/schemas/homepage-section-form.d.ts

@@ -0,0 +1,22 @@
+import { z } from "zod";
+/**
+ * 🛑 `annotate()` must be the OUTERMOST call on each field — it keys a WeakMap
+ * by schema instance and every zod wrapper returns a new one.
+ */
+export declare const homepageSectionFormSchema: z.ZodObject<{
+    sectionType: z.ZodString;
+    order: z.ZodOptional<z.ZodNumber>;
+    enabled: z.ZodBoolean;
+    configJson: z.ZodEffects<z.ZodString, string, string>;
+}, "strip", z.ZodTypeAny, {
+    enabled: boolean;
+    sectionType: string;
+    configJson: string;
+    order?: number | undefined;
+}, {
+    enabled: boolean;
+    sectionType: string;
+    configJson: string;
+    order?: number | undefined;
+}>;
+export type HomepageSectionFormValues = z.infer<typeof homepageSectionFormSchema>;

package/dist/features/admin/schemas/homepage-section-form.js

@@ -0,0 +1,68 @@
+/*
+ * WHY: `AdminSectionsView` rendered a `<Form>` with no `schema` prop. The route
+ *      validated `order` / `enabled` / `config`, so nothing invalid was ever
+ *      stored — but a bad value came back as a 400 banner after a round-trip
+ *      rather than as an error on the field that caused it.
+ * WHAT: The homepage-section form schema.
+ *
+ * ## `config` stays open, deliberately
+ *
+ * Its shape differs per section type across 21 types, and the route models it
+ * the same way (`z.object({}).passthrough()`). Naming a fixed shape here would
+ * strip whatever the current type actually needs — the exact defect that made
+ * `productBaseSchema` eat every per-type listing field. The form parses it as
+ * JSON and reports malformed input; the per-type meaning stays with the
+ * section renderer that owns it.
+ *
+ * EXPORTS:
+ *   homepageSectionFormSchema, type HomepageSectionFormValues
+ *
+ * @tag domain:admin,homepage
+ * @tag layer:schema
+ * @tag pattern:none
+ * @tag access:isomorphic
+ * @tag consumers:AdminSectionsView
+ * @tag sideEffects:none
+ */
+import { z } from "zod";
+import { annotate } from "../../shell/field-ui-meta";
+import { normalizeError } from "../../../errors/normalize";
+/**
+ * 🛑 `annotate()` must be the OUTERMOST call on each field — it keys a WeakMap
+ * by schema instance and every zod wrapper returns a new one.
+ */
+export const homepageSectionFormSchema = z.object({
+    sectionType: annotate(z.string().min(1, "Choose a section type."), {
+        section: "basics", sectionLabel: "Section", sectionRequired: true,
+        quick: true, order: 1, row: "pair",
+    }),
+    order: annotate(z.coerce
+        .number({ invalid_type_error: "Order must be a number." })
+        .int("Order must be a whole number.")
+        .min(0, "Order cannot be negative.")
+        .optional(), { section: "basics", order: 2, row: "pair" }),
+    enabled: annotate(z.boolean(), {
+        section: "basics", order: 3, row: "quarter",
+    }),
+    configJson: annotate(z.string().refine(isParsableJson, { message: "Config must be valid JSON." }), {
+        section: "config", sectionLabel: "Configuration",
+        order: 1, row: "full", kind: "list",
+    }),
+});
+/** Hoisted so the `annotate()` call above stays a simple two-argument call. */
+function isParsableJson(value) {
+    if (!value.trim())
+        return true;
+    try {
+        JSON.parse(value);
+        return true;
+    }
+    catch (_err) {
+        // Normalized rather than suppressed. The parse failure IS the return value
+        // here — `false` answers the only question this asks — but the project
+        // forbids adding new suppression markers, and this is the same shape
+        // AdminSectionsView already uses for the very same JSON parse.
+        void normalizeError(_err);
+        return false;
+    }
+}