@mohasinac/appkit 4.60.1 → 4.61.0

package/dist/errors/firestore-codes.js

@@ -0,0 +1,52 @@
+/**
+ * Firestore / gRPC error-code predicates, in one place.
+ *
+ * ## Why this file exists
+ *
+ * `isAlreadyExists` had been written THREE times — in the gateway-events,
+ * payment-cases and protection-claims repositories, two of them byte-identical
+ * — and each copy duck-typed the caught error the same way:
+ *
+ *     const code = (err as { code?: unknown }).code;
+ *
+ * That is past the Rule of Three, and `audit-unknown-leakage` was reporting all
+ * six of those field reads: casting to `{ code?: unknown }` narrows the OBJECT
+ * and leaves the FIELD unknown, so every comparison below it is unchecked.
+ * Naming the shape once gives the comparisons a real type and leaves one
+ * implementation to fix when the SDK changes what it throws.
+ *
+ * ## 🛑 Why three checks and not one
+ *
+ * The Admin SDK has surfaced this condition as a numeric gRPC code, as a string
+ * code, and as a bare message, depending on version and transport. All three
+ * are tested, and the message test is in ADDITION to the codes rather than
+ * instead of them — a stringly-typed guard alone is what breaks silently on an
+ * SDK bump, and the failure mode is a create that reports success while having
+ * collided.
+ */
+/** gRPC status 6. The numeric form, which is what the Admin SDK usually sets. */
+export const GRPC_ALREADY_EXISTS = 6;
+/** Narrow an unknown thrown value to the fields these predicates read. */
+function asFirestoreError(err) {
+    if (typeof err !== "object" || err === null)
+        return null;
+    return err;
+}
+/**
+ * Did Firestore refuse this write because the document already exists?
+ *
+ * The one question every `createWithId`-style insert needs answered, and the
+ * reason it matters is that "already there" is usually SUCCESS for an
+ * idempotent writer — a claim, a case or an inbox row that a retry re-sends.
+ * Treating it as a failure turns a safe retry into a 500.
+ */
+export function isAlreadyExistsError(err) {
+    const e = asFirestoreError(err);
+    if (!e)
+        return false;
+    if (e.code === GRPC_ALREADY_EXISTS)
+        return true;
+    if (e.code === "already-exists" || e.code === "ALREADY_EXISTS")
+        return true;
+    return typeof e.message === "string" && e.message.includes("ALREADY_EXISTS");
+}

package/dist/errors/index.d.ts

@@ -10,7 +10,6 @@ export { NotFoundError } from "./not-found-error";
 export { ConflictError } from "./conflict-error";
 export { DatabaseError } from "./database-error";
 export { PaymentProviderUnreachableError } from "./payment-provider-unreachable";
-export { handleApiError, logError, isAppError } from "./error-handler";
 export { mapToHttpError, HTTP_ERROR_CODES, type MappedError, type HttpErrorCode, } from "./error-mapping";
 export { ERROR_DISPLAY_MAP, getErrorDisplay, toUserMessage, GENERIC_USER_MESSAGE, type ErrorDisplayEntry, } from "./error-display-map";
 export { safeRead, installDegradedReadReporter, type DegradedReadReport, } from "./safe-read";

package/dist/errors/index.js

@@ -13,8 +13,18 @@ export { NotFoundError } from "./not-found-error.js";
 export { ConflictError } from "./conflict-error.js";
 export { DatabaseError } from "./database-error.js";
 export { PaymentProviderUnreachableError } from "./payment-provider-unreachable.js";
-// error-handler uses `next/server` — only import in server/API-route contexts
-export { handleApiError, logError, isAppError } from "./error-handler.js";
+/*
+ * 🛑 `error-handler` is deliberately NOT re-exported here. Import it from
+ * "./error-handler" directly.
+ *
+ * It does `import { NextResponse } from "next/server.js"`, and 83 files
+ * import THIS barrel — including repositories reachable from the Firebase
+ * Functions entry. So the barrel dragged Next's server runtime into the tsup
+ * bundle, which died on two unresolved `react-server-dom-webpack/*` requires
+ * and two `@vercel/og` .wasm files, naming none of the files responsible.
+ * The old line carried a comment saying "only import in server/API-route
+ * contexts" — a convention nothing could enforce. Root Cause #18.
+ */
 // Code→HTTP mapper (server) — and the i18n / inline-field map (client-safe)
 export { mapToHttpError, HTTP_ERROR_CODES, } from "./error-mapping.js";
 export { ERROR_DISPLAY_MAP, getErrorDisplay, toUserMessage, GENERIC_USER_MESSAGE, } from "./error-display-map.js";

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

@@ -56,6 +56,9 @@ export function AdminCouponEditorView({ couponId, onSaved, onDeleted, embedded,
         minPurchase: "",
         buyQuantity: "1",
         getQuantity: "1",
+        // Blank, not a number — the ceiling is optional and a default here would
+        // silently cap a new BOGO coupon the admin never meant to cap.
+        maxItemPrice: "",
         totalLimit: "",
         perUserLimit: "",
         currentUsage: 0,
@@ -101,6 +104,7 @@ export function AdminCouponEditorView({ couponId, onSaved, onDeleted, embedded,
             minPurchase: c.discount?.minPurchase !== undefined ? String(c.discount.minPurchase) : "",
             buyQuantity: c.bxgy?.buyQuantity !== undefined ? String(c.bxgy.buyQuantity) : "1",
             getQuantity: c.bxgy?.getQuantity !== undefined ? String(c.bxgy.getQuantity) : "1",
+            maxItemPrice: c.bxgy?.maxItemPrice !== undefined ? String(c.bxgy.maxItemPrice) : "",
             totalLimit: c.usage?.totalLimit !== undefined ? String(c.usage.totalLimit) : "",
             perUserLimit: c.usage?.perUserLimit !== undefined ? String(c.usage.perUserLimit) : "",
             currentUsage: c.usage?.currentUsage ?? 0,
@@ -147,6 +151,10 @@ export function AdminCouponEditorView({ couponId, onSaved, onDeleted, embedded,
                     bxgy: {
                         buyQuantity: num(draft.buyQuantity) ?? 1,
                         getQuantity: num(draft.getQuantity) ?? 1,
+                        // `num("")` is undefined, and an undefined ceiling is "no limit" —
+                        // which is what a blank box should mean. Do not `?? 0` it: zero
+                        // would disqualify every unit and silently zero the coupon.
+                        maxItemPrice: num(draft.maxItemPrice),
                     },
                 }),
                 usage: {

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

@@ -52,7 +52,7 @@ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-run
  */
 import React, { useState } from "react";
 import { sieveFilter, SIEVE_OP, sortBy, } from "@mohasinac/appkit/client";
-import { FilterChipGroup, ListingLayout, Modal, RecordDetailModal, Row, RowActionMenu, Stack, Text, Button, } from "../../../ui/index.js";
+import { FilterChipGroup, ListingLayout, Modal, RecordDetailModal, Row, RowActionMenu, Span, Stack, Text, Button, } from "../../../ui/index.js";
 import { ADMIN_ENDPOINTS } from "../../../constants/api-endpoints.js";
 import { ADMIN_GATEWAY_EVENT_KIND_TABS, ADMIN_GATEWAY_EVENT_STATUS_TABS, } from "../constants/filter-tabs.js";
 import { toRecordArray, toRelativeDate, toStringValue, } from "../hooks/useAdminListingData.js";
@@ -205,5 +205,5 @@ export function AdminGatewayEventsView({ children, ...props }) {
                  */
                 metadata: detail && detail.payload && typeof detail.payload === "object"
                     ? detail.payload
-                    : undefined, footer: detail ? (_jsx(Button, { variant: "outline", size: "sm", onClick: () => setReopenId(toStringValue(detail.id, "")), children: "Reopen for redelivery" })) : undefined }), _jsx(Modal, { isOpen: reopenId !== null, onClose: () => setReopenId(null), title: "Reopen this event for redelivery", size: "sm", children: _jsxs(Stack, { gap: "md", children: [_jsxs(Text, { size: "sm", children: ["This clears the terminal flag and the attempt count so the inbox will ", _jsx("strong", { children: "accept" }), " the next delivery of this event instead of refusing it as a duplicate."] }), _jsx(Row, { surface: "warning-surface", padding: "sm", rounded: "default", children: _jsxs(Text, { size: "sm", color: "warning", children: ["It does not reprocess anything by itself. Nothing outside the webhook route knows how to handle an event, so after this you still need to press ", _jsx("strong", { children: "Resend" }), " on this delivery in the gateway dashboard \u2014 or wait for the gateway\u2019s own retry."] }) }), _jsxs(Row, { justify: "end", gap: "sm", children: [_jsx(Button, { variant: "ghost", onClick: () => setReopenId(null), disabled: busy, children: "Cancel" }), _jsx(Button, { variant: "primary", isLoading: busy, disabled: busy, onClick: () => reopen(reopenId), children: "Reopen" })] })] }) })] }));
+                    : undefined, footer: detail ? (_jsx(Button, { variant: "outline", size: "sm", onClick: () => setReopenId(toStringValue(detail.id, "")), children: "Reopen for redelivery" })) : undefined }), _jsx(Modal, { isOpen: reopenId !== null, onClose: () => setReopenId(null), title: "Reopen this event for redelivery", size: "sm", children: _jsxs(Stack, { gap: "md", children: [_jsxs(Text, { size: "sm", children: ["This clears the terminal flag and the attempt count so the inbox will ", _jsx(Span, { weight: "semibold", children: "accept" }), " the next delivery of this event instead of refusing it as a duplicate."] }), _jsx(Row, { surface: "warning-surface", padding: "sm", rounded: "default", children: _jsxs(Text, { size: "sm", color: "warning", children: ["It does not reprocess anything by itself. Nothing outside the webhook route knows how to handle an event, so after this you still need to press ", _jsx(Span, { weight: "semibold", children: "Resend" }), " on this delivery in the gateway dashboard \u2014 or wait for the gateway\u2019s own retry."] }) }), _jsxs(Row, { justify: "end", gap: "sm", children: [_jsx(Button, { variant: "ghost", onClick: () => setReopenId(null), disabled: busy, children: "Cancel" }), _jsx(Button, { variant: "primary", isLoading: busy, disabled: busy, onClick: () => reopen(reopenId), children: "Reopen" })] })] }) })] }));
 }

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

@@ -211,6 +211,8 @@ export function DataListingView({ config, }) {
      * which is the same as having no label at all.
      */
     const rowEditLabel = React.useCallback((row) => {
+        // `string | undefined`, not `unknown`: a row primary is a label or it
+        // is absent, and the `typeof` test below is a real narrowing either way.
         const primary = row.primary;
         const name = typeof primary === "string" && primary.trim() ? primary.trim() : row.id;
         return `${ROW_ACTION_META[ROW_ACTION_ID.EDIT].label} ${name}`;

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

@@ -79,7 +79,10 @@ export function AdminStatCard({ label, value, sub, icon, gradient = "brand", cla
         : `${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 && (
+    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(Text, { as: "span", "aria-hidden": "true", children: [trendArrow, " "] }), trendText, trendLabel ? (_jsxs(Text, { as: "span", size: "xs", color: "muted", weight: "normal", children: [" ", trendLabel] })) : null] })) : (
+                    /* A layout placeholder keeping the grid cell occupied — <Div> is
+                       the primitive for that; a bare <span/> carries no semantics. */
+                    _jsx(Div, {})), showSpark && (
                     /*
                       🛑 `aria-hidden`, with NO accessible label. A sparkline is a
                       decorative restatement of a trend already given in words

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

@@ -1,3 +1,4 @@
+import type { FirestoreDocument } from "../../../schemas/types";
 /**
  * Site Settings Repository
  *
@@ -26,7 +27,7 @@ import { SiteSettingsDocument, SiteSettingsCredentialsMasked, SiteSettingsUpdate
  *   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>;
+export declare function toDottedPaths(input: FirestoreDocument, prefix?: string): FirestoreDocument;
 /**
  * Repository for site settings management
  *

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

@@ -38,6 +38,13 @@ import { decryptSecret, encryptSecret, maskSecret } from "../../../security/inde
  *   anything whose prototype is not `Object.prototype`, which also covers
  *   `FieldValue` sentinels and `Timestamp` itself.
  */
+/*
+ * `FirestoreDocument`, not `Record<string, unknown>` — its own docstring says
+ * "use as the document shape for Firestore-backed repositories and mapDoc
+ * helpers". `unknown` values made every branch below unchecked, which is what
+ * audit-unknown-leakage reports; `FirestoreValue` admits exactly what Firestore
+ * round-trips (JSON + Date + undefined) and nothing else.
+ */
 export function toDottedPaths(input, prefix = "") {
     const out = {};
     for (const [key, value] of Object.entries(input)) {

package/dist/features/auctions/components/MarketplaceAuctionCard.js

@@ -202,5 +202,5 @@ export function MarketplaceAuctionCard({ product, buyoutPrice, className = "", v
      * Sibling of the card, never a child — see the prop's docstring. `z-20`
      * clears this card's own overlays, which all sit at `z-10`.
      */
-    return (_jsxs(Div, { className: "flex h-full flex-col", children: [card, _jsx(Div, { className: "flex justify-end px-[var(--appkit-space-3)] pb-[var(--appkit-space-3)]", children: ownerActions })] }));
+    return (_jsxs(Div, { layout: "flex-col", className: "h-full", children: [card, _jsx(Div, { layout: "flex", justify: "end", className: "px-[var(--appkit-space-3)] pb-[var(--appkit-space-3)]", children: ownerActions })] }));
 }

package/dist/features/catalogue/actions/approve-catalogue-listing.d.ts

@@ -1,4 +1,4 @@
-import { type ActionResult } from "@mohasinac/appkit/server";
+import { type ActionResult } from "../../../_internal/shared/types/action-result";
 /**
  * Admin path — approves a buyer's "Request to sell", creating the product
  * under the platform's own consignment store (not the buyer's, since a

package/dist/features/catalogue/actions/approve-catalogue-listing.js

@@ -1,5 +1,16 @@
 "use server";
-import { wrapAction } from "@mohasinac/appkit/server";
+/*
+ * 🛑 From the DEFINING module, never "@mohasinac/appkit/server".
+ *
+ * appkit importing its own public server barrel is a self-reference that drags
+ * the whole server surface in behind it — `dist/server.js` reaches next/og,
+ * next/navigation, next/headers and driver.js. Twenty `actions.ts` files did
+ * this for two symbols, and because `obligationSweep` reaches one of them, the
+ * Firebase Functions tsup bundle (noExternal: appkit) had to resolve Next:
+ * it failed on two `react-server-dom-webpack/*` requires and two @vercel/og
+ * .wasm files, naming none of the responsible files. Root Cause #18.
+ */
+import { wrapAction } from "../../../_internal/shared/types/action-result.js";
 import { catalogueRepository } from "../../../repositories/index.js";
 import { requireRoleUser } from "../../../providers/auth-firebase/helpers.js";
 import { isAdminUser } from "../../../features/auth/role-predicates.js";

package/dist/features/catalogue/actions/list-from-catalogue.d.ts

@@ -1,4 +1,4 @@
-import { type ActionResult } from "@mohasinac/appkit/server";
+import { type ActionResult } from "../../../_internal/shared/types/action-result";
 /**
  * Direct-listing path — turns a catalogue item straight into a real listing,
  * no approval queue. Two callers:

package/dist/features/catalogue/actions/list-from-catalogue.js

@@ -1,5 +1,16 @@
 "use server";
-import { wrapAction } from "@mohasinac/appkit/server";
+/*
+ * 🛑 From the DEFINING module, never "@mohasinac/appkit/server".
+ *
+ * appkit importing its own public server barrel is a self-reference that drags
+ * the whole server surface in behind it — `dist/server.js` reaches next/og,
+ * next/navigation, next/headers and driver.js. Twenty `actions.ts` files did
+ * this for two symbols, and because `obligationSweep` reaches one of them, the
+ * Firebase Functions tsup bundle (noExternal: appkit) had to resolve Next:
+ * it failed on two `react-server-dom-webpack/*` requires and two @vercel/og
+ * .wasm files, naming none of the responsible files. Root Cause #18.
+ */
+import { wrapAction } from "../../../_internal/shared/types/action-result.js";
 import { catalogueRepository, storeRepository } from "../../../repositories/index.js";
 import { requireRoleUser } from "../../../providers/auth-firebase/helpers.js";
 import { isAdminUser } from "../../../features/auth/role-predicates.js";

package/dist/features/catalogue/actions/submit-for-approval.d.ts

@@ -1,4 +1,4 @@
-import { type ActionResult } from "@mohasinac/appkit/server";
+import { type ActionResult } from "../../../_internal/shared/types/action-result";
 /**
  * Buyer path — requests admin list the item on their behalf. Flips
  * listingStatus to "pending_admin_approval"; the admin-notification fan-out

package/dist/features/catalogue/actions/submit-for-approval.js

@@ -1,5 +1,16 @@
 "use server";
-import { wrapAction } from "@mohasinac/appkit/server";
+/*
+ * 🛑 From the DEFINING module, never "@mohasinac/appkit/server".
+ *
+ * appkit importing its own public server barrel is a self-reference that drags
+ * the whole server surface in behind it — `dist/server.js` reaches next/og,
+ * next/navigation, next/headers and driver.js. Twenty `actions.ts` files did
+ * this for two symbols, and because `obligationSweep` reaches one of them, the
+ * Firebase Functions tsup bundle (noExternal: appkit) had to resolve Next:
+ * it failed on two `react-server-dom-webpack/*` requires and two @vercel/og
+ * .wasm files, naming none of the responsible files. Root Cause #18.
+ */
+import { wrapAction } from "../../../_internal/shared/types/action-result.js";
 import { catalogueRepository } from "../../../repositories/index.js";
 import { requireRoleUser } from "../../../providers/auth-firebase/helpers.js";
 import { ValidationError, AuthorizationError } from "../../../errors/index.js";

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

@@ -113,6 +113,25 @@ export interface PriceObservationDocument {
     createdAt: Date;
 }
 export declare const PRICE_OBSERVATION_COLLECTION = "priceObservations";
+/**
+ * Field names, so a query names them through a constant rather than a literal.
+ *
+ * `audit-route-nav-field-constants` R3 blocks a raw `where("categoryId", …)`,
+ * and the constants it suggested for this one were
+ * `MODEL_COMPOSITION_FIELDS.CATEGORY_ID | BEY_FIELDS.CATEGORY_ID` — two
+ * different documents that happen to share the field NAME. Borrowing either
+ * would make the query read as though it were about that document, which is
+ * worse than the literal it replaced. A price observation needs its own.
+ */
+export declare const PRICE_OBSERVATION_FIELDS: {
+    readonly CATEGORY_ID: "categoryId";
+    readonly AMOUNT: "amount";
+    readonly CURRENCY: "currency";
+    readonly KIND: "kind";
+    readonly SEEN_AT: "seenAt";
+    readonly SOLD_OUT: "soldOut";
+    readonly SOURCE_KEY: "sourceKey";
+};
 /**
  * Hard ceiling on one leaf's observation read.
  *

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

@@ -59,6 +59,25 @@
  */
 import { BaseRepository } from "../../../providers/db-firebase/index.js";
 export const PRICE_OBSERVATION_COLLECTION = "priceObservations";
+/**
+ * Field names, so a query names them through a constant rather than a literal.
+ *
+ * `audit-route-nav-field-constants` R3 blocks a raw `where("categoryId", …)`,
+ * and the constants it suggested for this one were
+ * `MODEL_COMPOSITION_FIELDS.CATEGORY_ID | BEY_FIELDS.CATEGORY_ID` — two
+ * different documents that happen to share the field NAME. Borrowing either
+ * would make the query read as though it were about that document, which is
+ * worse than the literal it replaced. A price observation needs its own.
+ */
+export const PRICE_OBSERVATION_FIELDS = {
+    CATEGORY_ID: "categoryId",
+    AMOUNT: "amount",
+    CURRENCY: "currency",
+    KIND: "kind",
+    SEEN_AT: "seenAt",
+    SOLD_OUT: "soldOut",
+    SOURCE_KEY: "sourceKey",
+};
 /**
  * Hard ceiling on one leaf's observation read.
  *
@@ -88,8 +107,8 @@ export class PriceObservationRepository extends BaseRepository {
      */
     async findForLeaf(categoryId, limit = PRICE_OBSERVATION_SCAN_LIMIT) {
         const snap = await this.getCollection()
-            .where("categoryId", "==", categoryId)
-            .orderBy("seenAt", "desc")
+            .where(PRICE_OBSERVATION_FIELDS.CATEGORY_ID, "==", categoryId)
+            .orderBy(PRICE_OBSERVATION_FIELDS.SEEN_AT, "desc")
             .limit(limit)
             .get();
         return snap.docs.map((d) => this.mapDoc(d));

package/dist/features/events/actions/event-actions.js

@@ -17,6 +17,7 @@ const ERR_EVENT_NOT_FOUND = "Event not found";
 import { coerceMediaField, getMediaUrl } from "../../../utils/index.js";
 import { finalizeStagedMediaField, finalizeStagedMediaObject, finalizeStagedMediaObjectArray, } from "../../media/finalize.js";
 import { hidePublicTestData } from "../../../_internal/server/features/tester/visibility.js";
+import { sortPinnedFirst } from "../utils/sort-pinned.js";
 // --- Admin: Create Event --------------------------------------------------
 export async function createEvent(adminId, input) {
     const finalizedCoverUrl = await finalizeStagedMediaField(getMediaUrl(input.coverImage) ??
@@ -139,7 +140,9 @@ export async function listPublicEvents(params) {
         pageSize,
     });
     // PUBLIC by name — it backs the homepage strip and /events.
-    return { ...result, items: hidePublicTestData(result.items) };
+    // `sortPinnedFirst` AFTER the test-data filter, so a pinned sandbox event
+    // cannot occupy the rail's first slot for a visitor who cannot see it.
+    return { ...result, items: sortPinnedFirst(hidePublicTestData(result.items)) };
 }
 /**
  * 🛑 ONLY `draft` IS HIDDEN. Every other status is public history.

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

@@ -135,6 +135,7 @@ const DEFAULT_DRAFT = {
     status: "draft",
     createdBy: "",
     allowGuestParticipation: false,
+    isPinned: false,
     discountPercent: "10",
     saleBannerText: "",
     couponId: "",
@@ -211,6 +212,72 @@ function SpinPrizesEditor({ values, onChange, }) {
     return (_jsxs(Stack, { gap: "sm", rounded: "lg", border: "default", padding: "sm", children: [_jsx(Text, { size: "xs", weight: "medium", color: "muted", children: "Spin prizes (weighted random)" }), values.spinPrizes.length === 0 && (_jsx(Text, { size: "xs", color: "muted", children: "No spin prizes yet. Add at least one to enable spinning." })), values.spinPrizes.map((p) => (_jsxs(Grid, { align: "end", gap: "xs", className: "grid-cols-12", children: [_jsx(Div, { className: "col-span-5", children: _jsx(Input, { label: "Label", value: p.label, onChange: (e) => onChange({ spinPrizes: values.spinPrizes.map((sp) => sp.id === p.id ? { ...sp, label: e.target.value } : sp) }), placeholder: "\u20B9100 off" }) }), _jsxs(Div, { className: "col-span-3", children: [_jsx(Text, { size: "xs", weight: "medium", className: "mb-1", children: "Coupon" }), _jsx(CouponInlineSelect, { scope: "admin", value: p.couponId ?? "", onChange: (id) => onChange({ spinPrizes: values.spinPrizes.map((sp) => sp.id === p.id ? { ...sp, couponId: id || undefined } : sp) }), placeholder: "Search\u2026", allowCreate: false })] }), _jsx(Div, { className: "col-span-2", children: _jsx(Input, { label: "Weight", type: "number", value: String(p.weight), onChange: (e) => onChange({ spinPrizes: values.spinPrizes.map((sp) => sp.id === p.id ? { ...sp, weight: Number(e.target.value) || 0 } : sp) }) }) }), _jsx(Row, { centered: true, className: "col-span-1", padding: "b-xs", children: _jsx(Toggle, { checked: p.isActive, onChange: (v) => onChange({ spinPrizes: values.spinPrizes.map((sp) => sp.id === p.id ? { ...sp, isActive: v } : sp) }), label: "" }) }), _jsx(Row, { centered: true, className: "col-span-1", padding: "b-xs", children: _jsx(Button, { variant: "ghost", type: "button", onClick: () => onChange({ spinPrizes: values.spinPrizes.filter((sp) => sp.id !== p.id) }), className: CLS_REMOVE_BTN_LG, "aria-label": "Remove prize", children: "\u00D7" }) })] }, p.id))), _jsx(Button, { type: "button", variant: "outline", size: "sm", onClick: () => onChange({ spinPrizes: [...values.spinPrizes, { id: `prize-${Date.now()}`, label: "", couponId: undefined, weight: 1, isActive: true }] }), children: "+ Add spin prize" }), _jsx(Input, { label: "Max spins per user", type: "number", value: values.spinMaxPerUser, onChange: (e) => onChange({ spinMaxPerUser: e.target.value }), placeholder: "1" }), _jsxs(Grid, { cols: 2, gap: "sm", children: [_jsx(Input, { label: "Spin window start", type: "datetime-local", value: values.spinWindowStart, onChange: (e) => onChange({ spinWindowStart: e.target.value }) }), _jsx(Input, { label: "Spin window end", type: "datetime-local", value: values.spinWindowEnd, onChange: (e) => onChange({ spinWindowEnd: e.target.value }) })] })] }));
 }
 // --- Component ---------------------------------------------------------------
+/**
+ * The API's event shape -> the editor's draft shape.
+ *
+ * A pure adapter at module scope. The extraction is not cosmetic: this was
+ * 45 lines of field mapping inside a `useEffect` inside a 455-line
+ * component, which is exactly where a wrong default hides.
+ *
+ * Every `|| ""` and `Boolean()` is load-bearing. An ABSENT field — any event
+ * predating the one that added it — must still seed a CONTROLLED input;
+ * `undefined` makes React treat it as uncontrolled and the field stops
+ * accepting edits.
+ *
+ * 🛑 `requireLogin: event.surveyConfig?.requireLogin !== false` is the one
+ * default deliberately INVERTED — absent means true, because a survey that
+ * silently stopped requiring a login would collect anonymous entries nobody
+ * asked for. Do not "tidy" it into `Boolean(...)`.
+ */
+function eventToDraft(event) {
+    return {
+        type: event.type || "sale",
+        title: event.title || "",
+        slug: event.slug || "",
+        description: event.description || "",
+        startsAt: toLocalDatetime(event.startsAt),
+        endsAt: toLocalDatetime(event.endsAt),
+        coverImageUrl: event.coverImageUrl || event.coverImage?.url || "",
+        tags: Array.isArray(event.tags) ? event.tags : [],
+        status: event.status || "draft",
+        createdBy: event.createdBy || "",
+        allowGuestParticipation: Boolean(event.allowGuestParticipation),
+        // `Boolean()` so an ABSENT field (every event predating the pin) seeds
+        // the toggle as off rather than leaving it `undefined`, which React
+        // would read as an uncontrolled input.
+        isPinned: Boolean(event.isPinned),
+        discountPercent: String(event.saleConfig?.discountPercent ?? 10),
+        saleBannerText: event.saleConfig?.bannerText || "",
+        couponId: event.offerConfig?.couponId || "",
+        displayCode: event.offerConfig?.displayCode || "",
+        offerBannerText: event.offerConfig?.bannerText || "",
+        pollOptions: event.pollConfig?.options?.length
+            ? event.pollConfig.options
+            : [{ id: "opt1", label: "" }, { id: "opt2", label: "" }],
+        allowMultiSelect: Boolean(event.pollConfig?.allowMultiSelect),
+        allowComment: Boolean(event.pollConfig?.allowComment),
+        resultsVisibility: event.pollConfig?.resultsVisibility || "always",
+        requireLogin: event.surveyConfig?.requireLogin !== false,
+        maxEntriesPerUser: String(event.surveyConfig?.maxEntriesPerUser ?? 1),
+        hasLeaderboard: Boolean(event.surveyConfig?.hasLeaderboard),
+        hasPointSystem: Boolean(event.surveyConfig?.hasPointSystem),
+        pointsLabel: event.surveyConfig?.pointsLabel ?? "Points",
+        entryReviewRequired: Boolean(event.surveyConfig?.entryReviewRequired),
+        surveyFields: Array.isArray(event.surveyConfig?.formFields) ? event.surveyConfig.formFields : [],
+        anonymous: Boolean(event.feedbackConfig?.anonymous),
+        feedbackFields: Array.isArray(event.feedbackConfig?.formFields) ? event.feedbackConfig.formFields : [],
+        hasRaffle: Boolean(event.hasRaffle),
+        raffleType: event.raffleType || "open_raffle",
+        raffleTopN: String(event.raffleTopN ?? 10),
+        rafflePrize: event.rafflePrize || "",
+        rafflePrizeCouponId: event.rafflePrizeCouponId || "",
+        rafflePrizeProductIds: Array.isArray(event.rafflePrizeProductIds) ? event.rafflePrizeProductIds : [],
+        spinPrizes: Array.isArray(event.spinPrizes) ? event.spinPrizes : [],
+        spinMaxPerUser: String(event.spinMaxPerUser ?? 1),
+        spinWindowStart: toLocalDatetime(event.spinWindowStart),
+        spinWindowEnd: toLocalDatetime(event.spinWindowEnd),
+    };
+}
 export function AdminEventEditorView({ eventId, onSaved, embedded, allowedTypes, ...rest }) {
     const isEdit = Boolean(eventId);
     const [draft, setDraft] = React.useState(DEFAULT_DRAFT);
@@ -243,49 +310,8 @@ export function AdminEventEditorView({ eventId, onSaved, embedded, allowedTypes,
         const event = eventQuery.data?.data ?? eventQuery.data;
         if (!event?.id)
             return;
-        setDraft({
-            type: event.type || "sale",
-            title: event.title || "",
-            slug: event.slug || "",
-            description: event.description || "",
-            startsAt: toLocalDatetime(event.startsAt),
-            endsAt: toLocalDatetime(event.endsAt),
-            coverImageUrl: event.coverImageUrl || event.coverImage?.url || "",
-            tags: Array.isArray(event.tags) ? event.tags : [],
-            status: event.status || "draft",
-            createdBy: event.createdBy || "",
-            allowGuestParticipation: Boolean(event.allowGuestParticipation),
-            discountPercent: String(event.saleConfig?.discountPercent ?? 10),
-            saleBannerText: event.saleConfig?.bannerText || "",
-            couponId: event.offerConfig?.couponId || "",
-            displayCode: event.offerConfig?.displayCode || "",
-            offerBannerText: event.offerConfig?.bannerText || "",
-            pollOptions: event.pollConfig?.options?.length
-                ? event.pollConfig.options
-                : [{ id: "opt1", label: "" }, { id: "opt2", label: "" }],
-            allowMultiSelect: Boolean(event.pollConfig?.allowMultiSelect),
-            allowComment: Boolean(event.pollConfig?.allowComment),
-            resultsVisibility: event.pollConfig?.resultsVisibility || "always",
-            requireLogin: event.surveyConfig?.requireLogin !== false,
-            maxEntriesPerUser: String(event.surveyConfig?.maxEntriesPerUser ?? 1),
-            hasLeaderboard: Boolean(event.surveyConfig?.hasLeaderboard),
-            hasPointSystem: Boolean(event.surveyConfig?.hasPointSystem),
-            pointsLabel: event.surveyConfig?.pointsLabel ?? "Points",
-            entryReviewRequired: Boolean(event.surveyConfig?.entryReviewRequired),
-            surveyFields: Array.isArray(event.surveyConfig?.formFields) ? event.surveyConfig.formFields : [],
-            anonymous: Boolean(event.feedbackConfig?.anonymous),
-            feedbackFields: Array.isArray(event.feedbackConfig?.formFields) ? event.feedbackConfig.formFields : [],
-            hasRaffle: Boolean(event.hasRaffle),
-            raffleType: event.raffleType || "open_raffle",
-            raffleTopN: String(event.raffleTopN ?? 10),
-            rafflePrize: event.rafflePrize || "",
-            rafflePrizeCouponId: event.rafflePrizeCouponId || "",
-            rafflePrizeProductIds: Array.isArray(event.rafflePrizeProductIds) ? event.rafflePrizeProductIds : [],
-            spinPrizes: Array.isArray(event.spinPrizes) ? event.spinPrizes : [],
-            spinMaxPerUser: String(event.spinMaxPerUser ?? 1),
-            spinWindowStart: toLocalDatetime(event.spinWindowStart),
-            spinWindowEnd: toLocalDatetime(event.spinWindowEnd),
-        });
+        // The 45-line field mapping lives in `eventToDraft` at module scope.
+        setDraft(eventToDraft(event));
         setSlugManual(true);
         setRaffleWinnerName(event.raffleWinnerDisplayName || "");
         setRaffleEntryCount(typeof event.raffleEntryCount === "number" ? event.raffleEntryCount : null);
@@ -304,6 +330,7 @@ export function AdminEventEditorView({ eventId, onSaved, embedded, allowedTypes,
                 endsAt: toISOString(draft.endsAt),
                 coverImageUrl: draft.coverImageUrl || undefined,
                 allowGuestParticipation: draft.allowGuestParticipation,
+                isPinned: draft.isPinned,
                 ...buildEventTypeConfig(draft),
                 ...buildEventRaffleFields(draft),
             };
@@ -397,11 +424,11 @@ export function AdminEventEditorView({ eventId, onSaved, embedded, allowedTypes,
         {
             id: "settings",
             label: "Settings",
-            fields: ["status", "allowGuestParticipation", "discountPercent", "saleBannerText", "couponId", "displayCode", "offerBannerText", "pollOptions", "resultsVisibility", "allowMultiSelect", "allowComment", "maxEntriesPerUser", "hasLeaderboard", "hasPointSystem", "pointsLabel", "entryReviewRequired", "surveyFields", "anonymous", "feedbackFields"],
+            fields: ["status", "allowGuestParticipation", "isPinned", "discountPercent", "saleBannerText", "couponId", "displayCode", "offerBannerText", "pollOptions", "resultsVisibility", "allowMultiSelect", "allowComment", "maxEntriesPerUser", "hasLeaderboard", "hasPointSystem", "pointsLabel", "entryReviewRequired", "surveyFields", "anonymous", "feedbackFields"],
             // Same: the offer-coupon, offer-display-code and poll-minimum-options
             // rules are all stated in eventDraftSchema's superRefine, which now
             // surfaces them inline on the field instead of as a step-blocking banner.
-            render: ({ values, onChange }) => (_jsxs(Stack, { gap: "md", children: [_jsx(Heading, { level: 3, className: "mb-2", children: "Event Settings" }), isEdit && (_jsx(Select, { label: "Status", value: values.status, options: EVENT_STATUS_OPTIONS, onChange: (e) => onChange({ status: e.target.value }) })), values.createdBy && (_jsxs(Stack, { gap: "none", children: [_jsx(Text, { size: "sm", weight: "medium", className: "mb-1", children: "Created by" }), _jsx(Text, { size: "sm", color: "muted", children: values.createdBy })] })), _jsxs(Stack, { gap: "xs", surface: "muted", rounded: "lg", border: "default", padding: "sm", children: [_jsx(Toggle, { checked: values.allowGuestParticipation, onChange: (v) => onChange({ allowGuestParticipation: v }), label: "Allow guest participation (no login required)" }), _jsx(Text, { size: "xs", color: "muted", children: "When enabled, unauthenticated visitors can participate in this event (poll vote, survey/feedback response, raffle entry, or wheel spin), identified by a hashed IP address instead of an account. Applies uniformly to whatever entry mechanism this event type uses." })] }), values.type === "sale" && (_jsxs(Stack, { gap: "xs", surface: "muted", rounded: "lg", border: "default", padding: "sm", children: [_jsx(Text, { size: "sm", weight: "semibold", color: "muted", children: "Sale configuration" }), _jsxs(Grid, { cols: 2, gap: "sm", children: [_jsx(Input, { label: "Discount %", type: "number", value: values.discountPercent, onChange: (e) => onChange({ discountPercent: e.target.value }), placeholder: "10" }), _jsx(Input, { label: "Banner text (optional)", value: values.saleBannerText, onChange: (e) => onChange({ saleBannerText: e.target.value }), placeholder: "Limited time \u2014 ends Sunday!" })] })] })), values.type === "offer" && (_jsxs(Stack, { gap: "xs", surface: "muted", rounded: "lg", border: "default", padding: "sm", children: [_jsx(Text, { size: "sm", weight: "semibold", color: "muted", children: "Offer configuration" }), _jsxs(Grid, { cols: 2, gap: "sm", children: [_jsxs(Div, { children: [_jsx(Text, { size: "sm", weight: "medium", className: "mb-1", children: "Coupon" }), _jsx(CouponInlineSelect, { scope: "admin", value: values.couponId, onChange: (id) => onChange({ couponId: id ?? "" }), placeholder: "Search coupons\u2026", allowCreate: false })] }), _jsx(Input, { label: "Display code", value: values.displayCode, onChange: (e) => onChange({ displayCode: e.target.value }), placeholder: "CHARIZARD25", required: true })] }), _jsx(Input, { label: "Banner text (optional)", value: values.offerBannerText, onChange: (e) => onChange({ offerBannerText: e.target.value }), placeholder: "Use CHARIZARD25 at checkout" })] })), values.type === "poll" && (_jsxs(Stack, { gap: "md", rounded: "xl", border: "default", padding: "md", children: [_jsx(Text, { size: "sm", weight: "semibold", color: "muted", children: "Poll configuration" }), _jsxs(Stack, { gap: "xs", children: [_jsx(Text, { size: "xs", color: "muted", children: "Options (minimum 2)" }), values.pollOptions.map((opt, idx) => (_jsxs(Row, { gap: "xs", children: [_jsx(Div, { className: "flex-1", children: _jsx(Input, { value: opt.label, onChange: (e) => onChange({ pollOptions: values.pollOptions.map((o) => o.id === opt.id ? { ...o, label: e.target.value } : o) }), placeholder: `Option ${idx + 1}` }) }), values.pollOptions.length > 2 && (_jsx(Button, { variant: "ghost", type: "button", onClick: () => onChange({ pollOptions: values.pollOptions.filter((o) => o.id !== opt.id) }), className: CLS_REMOVE_BTN_PX2, "aria-label": "Remove option", children: "\u00D7" }))] }, opt.id))), _jsx(Button, { type: "button", variant: "outline", size: "sm", onClick: () => onChange({ pollOptions: [...values.pollOptions, { id: `opt${Date.now()}`, label: "" }] }), children: "+ Add option" })] }), _jsx(Select, { label: "Results visibility", value: values.resultsVisibility, options: POLL_VISIBILITY_OPTIONS, onChange: (e) => onChange({ resultsVisibility: e.target.value }) }), _jsxs(Stack, { gap: "sm", children: [_jsx(Toggle, { checked: values.allowMultiSelect, onChange: (v) => onChange({ allowMultiSelect: v }), label: "Allow multi-select" }), _jsx(Toggle, { checked: values.allowComment, onChange: (v) => onChange({ allowComment: v }), label: "Allow comment with vote" })] })] })), values.type === "survey" && (_jsxs(Stack, { gap: "md", rounded: "xl", border: "default", padding: "md", children: [_jsx(Text, { size: "sm", weight: "semibold", color: "muted", children: "Survey configuration" }), _jsxs(Grid, { cols: 2, gap: "sm", children: [_jsx(Input, { label: "Max entries per user", type: "number", value: values.maxEntriesPerUser, onChange: (e) => onChange({ maxEntriesPerUser: e.target.value }), placeholder: "1" }), values.hasPointSystem && (_jsx(Input, { label: "Points label", value: values.pointsLabel, onChange: (e) => onChange({ pointsLabel: e.target.value }), placeholder: "Points" }))] }), _jsxs(Stack, { gap: "xs", children: [_jsx(Toggle, { checked: values.requireLogin, onChange: (v) => onChange({ requireLogin: v }), label: "Require login to participate" }), _jsx(Toggle, { checked: values.hasLeaderboard, onChange: (v) => onChange({ hasLeaderboard: v }), label: "Show leaderboard" }), _jsx(Toggle, { checked: values.hasPointSystem, onChange: (v) => onChange({ hasPointSystem: v }), label: "Enable point system" }), _jsx(Toggle, { checked: values.entryReviewRequired, onChange: (v) => onChange({ entryReviewRequired: v }), label: "Require employee review before entry is approved" })] }), _jsx(FormFieldBuilder, { fields: values.surveyFields, setFields: (f) => onChange({ surveyFields: f }) })] })), values.type === "feedback" && (_jsxs(Stack, { gap: "md", rounded: "xl", border: "default", padding: "md", children: [_jsx(Text, { size: "sm", weight: "semibold", color: "muted", children: "Feedback configuration" }), _jsx(Toggle, { checked: values.anonymous, onChange: (v) => onChange({ anonymous: v }), label: "Allow anonymous submissions" }), _jsx(FormFieldBuilder, { fields: values.feedbackFields, setFields: (f) => onChange({ feedbackFields: f }) })] }))] })),
+            render: ({ values, onChange }) => (_jsxs(Stack, { gap: "md", children: [_jsx(Heading, { level: 3, className: "mb-2", children: "Event Settings" }), isEdit && (_jsx(Select, { label: "Status", value: values.status, options: EVENT_STATUS_OPTIONS, onChange: (e) => onChange({ status: e.target.value }) })), values.createdBy && (_jsxs(Stack, { gap: "none", children: [_jsx(Text, { size: "sm", weight: "medium", className: "mb-1", children: "Created by" }), _jsx(Text, { size: "sm", color: "muted", children: values.createdBy })] })), _jsxs(Stack, { gap: "xs", surface: "muted", rounded: "lg", border: "default", padding: "sm", children: [_jsx(Toggle, { checked: values.allowGuestParticipation, onChange: (v) => onChange({ allowGuestParticipation: v }), label: "Allow guest participation (no login required)" }), _jsx(Text, { size: "xs", color: "muted", children: "When enabled, unauthenticated visitors can participate in this event (poll vote, survey/feedback response, raffle entry, or wheel spin), identified by a hashed IP address instead of an account. Applies uniformly to whatever entry mechanism this event type uses." })] }), _jsxs(Stack, { gap: "xs", surface: "muted", rounded: "lg", border: "default", padding: "sm", children: [_jsx(Toggle, { checked: values.isPinned, onChange: (v) => onChange({ isPinned: v }), label: "Pin to the top of Events" }), _jsx(Text, { size: "xs", color: "muted", children: "Pinned events are listed first on the Events page and in the homepage strip, ahead of the usual soonest-first order. A pinned event still has to be Active to appear at all \u2014 pinning does not publish it." })] }), values.type === "sale" && (_jsxs(Stack, { gap: "xs", surface: "muted", rounded: "lg", border: "default", padding: "sm", children: [_jsx(Text, { size: "sm", weight: "semibold", color: "muted", children: "Sale configuration" }), _jsxs(Grid, { cols: 2, gap: "sm", children: [_jsx(Input, { label: "Discount %", type: "number", value: values.discountPercent, onChange: (e) => onChange({ discountPercent: e.target.value }), placeholder: "10" }), _jsx(Input, { label: "Banner text (optional)", value: values.saleBannerText, onChange: (e) => onChange({ saleBannerText: e.target.value }), placeholder: "Limited time \u2014 ends Sunday!" })] })] })), values.type === "offer" && (_jsxs(Stack, { gap: "xs", surface: "muted", rounded: "lg", border: "default", padding: "sm", children: [_jsx(Text, { size: "sm", weight: "semibold", color: "muted", children: "Offer configuration" }), _jsxs(Grid, { cols: 2, gap: "sm", children: [_jsxs(Div, { children: [_jsx(Text, { size: "sm", weight: "medium", className: "mb-1", children: "Coupon" }), _jsx(CouponInlineSelect, { scope: "admin", value: values.couponId, onChange: (id) => onChange({ couponId: id ?? "" }), placeholder: "Search coupons\u2026", allowCreate: false })] }), _jsx(Input, { label: "Display code", value: values.displayCode, onChange: (e) => onChange({ displayCode: e.target.value }), placeholder: "CHARIZARD25", required: true })] }), _jsx(Input, { label: "Banner text (optional)", value: values.offerBannerText, onChange: (e) => onChange({ offerBannerText: e.target.value }), placeholder: "Use CHARIZARD25 at checkout" })] })), values.type === "poll" && (_jsxs(Stack, { gap: "md", rounded: "xl", border: "default", padding: "md", children: [_jsx(Text, { size: "sm", weight: "semibold", color: "muted", children: "Poll configuration" }), _jsxs(Stack, { gap: "xs", children: [_jsx(Text, { size: "xs", color: "muted", children: "Options (minimum 2)" }), values.pollOptions.map((opt, idx) => (_jsxs(Row, { gap: "xs", children: [_jsx(Div, { className: "flex-1", children: _jsx(Input, { value: opt.label, onChange: (e) => onChange({ pollOptions: values.pollOptions.map((o) => o.id === opt.id ? { ...o, label: e.target.value } : o) }), placeholder: `Option ${idx + 1}` }) }), values.pollOptions.length > 2 && (_jsx(Button, { variant: "ghost", type: "button", onClick: () => onChange({ pollOptions: values.pollOptions.filter((o) => o.id !== opt.id) }), className: CLS_REMOVE_BTN_PX2, "aria-label": "Remove option", children: "\u00D7" }))] }, opt.id))), _jsx(Button, { type: "button", variant: "outline", size: "sm", onClick: () => onChange({ pollOptions: [...values.pollOptions, { id: `opt${Date.now()}`, label: "" }] }), children: "+ Add option" })] }), _jsx(Select, { label: "Results visibility", value: values.resultsVisibility, options: POLL_VISIBILITY_OPTIONS, onChange: (e) => onChange({ resultsVisibility: e.target.value }) }), _jsxs(Stack, { gap: "sm", children: [_jsx(Toggle, { checked: values.allowMultiSelect, onChange: (v) => onChange({ allowMultiSelect: v }), label: "Allow multi-select" }), _jsx(Toggle, { checked: values.allowComment, onChange: (v) => onChange({ allowComment: v }), label: "Allow comment with vote" })] })] })), values.type === "survey" && (_jsxs(Stack, { gap: "md", rounded: "xl", border: "default", padding: "md", children: [_jsx(Text, { size: "sm", weight: "semibold", color: "muted", children: "Survey configuration" }), _jsxs(Grid, { cols: 2, gap: "sm", children: [_jsx(Input, { label: "Max entries per user", type: "number", value: values.maxEntriesPerUser, onChange: (e) => onChange({ maxEntriesPerUser: e.target.value }), placeholder: "1" }), values.hasPointSystem && (_jsx(Input, { label: "Points label", value: values.pointsLabel, onChange: (e) => onChange({ pointsLabel: e.target.value }), placeholder: "Points" }))] }), _jsxs(Stack, { gap: "xs", children: [_jsx(Toggle, { checked: values.requireLogin, onChange: (v) => onChange({ requireLogin: v }), label: "Require login to participate" }), _jsx(Toggle, { checked: values.hasLeaderboard, onChange: (v) => onChange({ hasLeaderboard: v }), label: "Show leaderboard" }), _jsx(Toggle, { checked: values.hasPointSystem, onChange: (v) => onChange({ hasPointSystem: v }), label: "Enable point system" }), _jsx(Toggle, { checked: values.entryReviewRequired, onChange: (v) => onChange({ entryReviewRequired: v }), label: "Require employee review before entry is approved" })] }), _jsx(FormFieldBuilder, { fields: values.surveyFields, setFields: (f) => onChange({ surveyFields: f }) })] })), values.type === "feedback" && (_jsxs(Stack, { gap: "md", rounded: "xl", border: "default", padding: "md", children: [_jsx(Text, { size: "sm", weight: "semibold", color: "muted", children: "Feedback configuration" }), _jsx(Toggle, { checked: values.anonymous, onChange: (v) => onChange({ anonymous: v }), label: "Allow anonymous submissions" }), _jsx(FormFieldBuilder, { fields: values.feedbackFields, setFields: (f) => onChange({ feedbackFields: f }) })] }))] })),
         },
         {
             id: "raffle",

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

@@ -8,6 +8,7 @@ import { sieveFilter, sieveMultiEq, sieveAnd, SIEVE_OP } from "../../../utils/si
 import { sortBy } from "../../../constants/sort.js";
 import { safeRead } from "../../../errors/safe-read.js";
 import { hidePublicTestData } from "../../../_internal/server/features/tester/visibility.js";
+import { sortPinnedFirst } from "../utils/sort-pinned.js";
 function sp(params, key) {
     const v = params[key];
     return Array.isArray(v) ? v[0] ?? "" : v ?? "";
@@ -69,7 +70,7 @@ export async function EventsListPageView({ searchParams = {} }) {
      * refetch threads the real viewer, so a signed-in tester still sees them.
      */
     const publicResult = result
-        ? { ...result, items: hidePublicTestData(result.items) }
+        ? { ...result, items: sortPinnedFirst(hidePublicTestData(result.items)) }
         : result;
     return (_jsx(Main, { children: _jsx(Section, { padding: "y-2xl", children: _jsxs(Container, { size: "xl", children: [_jsx(Heading, { level: 1, className: "mb-8", color: "primary", size: "3xl", weight: "semibold", children: "Events" }), _jsx(AdSlot, { id: "listing-sidebar-top", className: "mb-6" }), _jsx(EventsIndexListing, { initialData: publicResult, facetCounts: facetCounts }), _jsx(AdSlot, { id: "listing-sidebar-bottom", className: "mt-8" })] }) }) }));
 }

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

@@ -17,6 +17,22 @@ export interface EventDocument extends BaseDocument {
     title: string;
     description: string;
     status: EventStatus;
+    /**
+     * Lift this event to the top of `/events` and the homepage rail, ahead of
+     * the `startsAt` ASC default.
+     *
+     * 🛑 DELIBERATELY NOT IN `EVENT_INDEXED_FIELDS` AND NOT SORTABLE IN SIEVE.
+     * A Firestore `orderBy` EXCLUDES every document that lacks the ordering
+     * field (Root Cause #100), and `isPinned` is absent from all 1 live event
+     * and every seeded row that is not pinned — so ordering by it would empty
+     * the events page entirely while answering HTTP 200. The ordering is
+     * applied in memory by `sortPinnedFirst`; see the bound stated there.
+     *
+     * Absent means not pinned. Do not default it to `false` on write — a
+     * written `false` and an absent field must stay interchangeable, because
+     * every event that predates this field has the latter.
+     */
+    isPinned?: boolean;
     /** Test-data flag — set on the shared admin-seeded test event; swept by testDataCleanup. */
     isTestData?: boolean;
     /** When isTestData, the cutoff after which testDataCleanup deletes this doc. */
@@ -134,6 +150,7 @@ export declare const EVENT_FIELDS: {
     readonly WINNER_IMAGES: "winnerImages";
     readonly ADDITIONAL_IMAGES: "additionalImages";
     readonly TAGS: "tags";
+    readonly IS_PINNED: "isPinned";
     readonly ALLOW_GUEST_PARTICIPATION: "allowGuestParticipation";
     readonly CREATED_BY: "createdBy";
     readonly CREATED_AT: "createdAt";

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

@@ -38,6 +38,7 @@ export const EVENT_FIELDS = {
     WINNER_IMAGES: "winnerImages",
     ADDITIONAL_IMAGES: "additionalImages",
     TAGS: "tags",
+    IS_PINNED: "isPinned",
     ALLOW_GUEST_PARTICIPATION: "allowGuestParticipation",
     CREATED_BY: "createdBy",
     CREATED_AT: "createdAt",