@mohasinac/appkit 4.60.1 → 4.62.0

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/ReferenceRecordEditor.js

@@ -64,7 +64,7 @@ export function ReferenceRecordEditor({ endpoint, noun, fields, publicHref, }) {
             catch (err) {
                 const e = normalizeError(err);
                 if (!cancelled)
-                    setLoadError(e.message);
+                    setLoadError(toUserMessage(e?.code, undefined, { fallback: "Could not load that record." }));
             }
             finally {
                 if (!cancelled)

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/hooks/useOptimisticRowFlag.d.ts

@@ -0,0 +1,33 @@
+import { type QueryKey } from "@tanstack/react-query";
+export interface UseOptimisticRowFlagOptions<T> {
+    /**
+     * Performs the write. Receives the row id and the value being set.
+     *
+     * 🛑 Send ONLY the field being changed. Several of this hook's consumers sit
+     * over repositories that merge a `config`/nested object by READING the
+     * document first; omitting that field short-circuits the read, so a toggle
+     * costs one write and no read.
+     */
+    mutate: (id: string, next: T) => Promise<unknown>;
+    /**
+     * Query keys to invalidate. Pass every key that renders this field —
+     * several of these records are read by a PUBLIC surface under a key of its
+     * own, and forgetting it leaves the storefront stale until its own TTL.
+     */
+    invalidate: readonly QueryKey[];
+    /** Toast copy. Receives the value that was set. */
+    successMessage: (next: T) => string;
+    /** Fallback when the thrown error carries no message. */
+    errorMessage?: string;
+}
+export interface UseOptimisticRowFlagReturn<T> {
+    /** `overrides[id] ?? row.value` — the value to render. */
+    overrides: Record<string, T>;
+    /** Resolve a row's current value against any pending override. */
+    resolve: (id: string, serverValue: T) => T;
+    /** The id currently being written, for a per-row disabled state. */
+    pendingId: string | null;
+    /** Fire the change. Safe to call from an `onChange` without awaiting. */
+    set: (id: string, next: T) => Promise<void>;
+}
+export declare function useOptimisticRowFlag<T>({ mutate, invalidate, successMessage, errorMessage, }: UseOptimisticRowFlagOptions<T>): UseOptimisticRowFlagReturn<T>;

package/dist/features/admin/hooks/useOptimisticRowFlag.js

@@ -0,0 +1,87 @@
+"use client";
+/*
+ * WHY: Eight listing views grew the same per-row "flip one field" control in
+ *      one change — homepage sections (`enabled`), carousel slides (`active`),
+ *      the six seller listing-type pages (`status`), seller bundles, grouped
+ *      listings, store categories, shipping configs and payout methods
+ *      (`isActive`). Every one needs an optimistic override so the switch
+ *      moves under the finger, a PATCH, an invalidate, and a rollback.
+ *
+ *      That is well past the Duplication Framework's Rule of Three, and the
+ *      bug-fix multiplier is the real argument: the rollback is subtly wrong
+ *      in the shape everyone writes first.
+ *
+ * 🛑 THE ROLLBACK BUG THIS EXISTS TO MAKE UNREPEATABLE
+ *
+ * The obvious implementation captures the previous override and writes it
+ * back on failure:
+ *
+ *     const prev = overrides[id];              // `undefined` on a row's
+ *     setOverrides((o) => ({...o, [id]: v}));  // FIRST toggle
+ *     catch { setOverrides((o) => ({...o, [id]: prev})); }
+ *
+ * `prev` is `undefined` the first time any given row is toggled, and writing
+ * `undefined` back is not the same as removing the key — a reader doing
+ * `overrides[id] ?? row.value` gets `undefined`, which for a boolean renders
+ * as `false`. So a FAILED toggle of a row the server holds as `true` leaves
+ * the UI asserting the opposite of the truth, which is worse than not having
+ * rolled back at all. `AdminProductsView.tsx` has this shape.
+ *
+ * The fix is to DELETE the key, which is what `clear` below does.
+ *
+ * 🛑 The key is cleared on SUCCESS too, and only AFTER the invalidation has
+ * settled. `invalidateQueries` resolves once active refetches finish, so by
+ * then `mapRows` is already reading the fresh server value and there is no
+ * visible flip-back-then-forward. An override that is never cleared pins the
+ * row forever and masks every later server-side change to it.
+ *
+ * EXPORTS: useOptimisticRowFlag, UseOptimisticRowFlagOptions
+ *
+ * @tag domain:admin,seller
+ * @tag layer:hook
+ * @tag pattern:none
+ * @tag access:client
+ * @tag consumers:AdminSectionsView,AdminCarouselView,SellerListingTypeView,SellerBundlesView,SellerGroupedListingsView,SellerStoreCategoriesView,SellerShippingConfigsView,SellerPayoutMethodsView
+ * @tag sideEffects:network
+ */
+import React from "react";
+import { useQueryClient } from "@tanstack/react-query";
+import { useToast } from "../../../ui/index.js";
+import { normalizeError } from "../../../errors/normalize.js";
+import { toUserMessage } from "../../../errors/error-display-map.js";
+export function useOptimisticRowFlag({ mutate, invalidate, successMessage, errorMessage = "Could not save that change.", }) {
+    const queryClient = useQueryClient();
+    const { showToast } = useToast();
+    const [overrides, setOverrides] = React.useState({});
+    const [pendingId, setPendingId] = React.useState(null);
+    const clear = React.useCallback((id) => {
+        setOverrides((prev) => {
+            if (!(id in prev))
+                return prev;
+            const next = { ...prev };
+            // DELETE, never write back a captured value — see the header.
+            delete next[id];
+            return next;
+        });
+    }, []);
+    const set = React.useCallback(async (id, next) => {
+        setOverrides((prev) => ({ ...prev, [id]: next }));
+        setPendingId(id);
+        try {
+            await mutate(id, next);
+            await Promise.all(invalidate.map((queryKey) => queryClient.invalidateQueries({ queryKey })));
+            clear(id);
+            showToast(successMessage(next), "success");
+        }
+        catch (err) {
+            const normalized = normalizeError(err);
+            clear(id);
+            showToast(toUserMessage(normalized.code, undefined, { fallback: errorMessage }), "error");
+        }
+        finally {
+            setPendingId(null);
+        }
+    }, [mutate, invalidate, queryClient, clear, showToast, successMessage, errorMessage]);
+    const resolve = React.useCallback((id, serverValue) => (id in overrides ? overrides[id] : serverValue), [overrides]);
+    return { overrides, resolve, pendingId, set };
+}

package/dist/features/admin/repository/notification.repository.d.ts

@@ -30,6 +30,21 @@ export declare class NotificationRepository extends BaseRepository<NotificationD
      * Get unread notification count for a user.
      */
     getUnreadCount(userId: string): Promise<number>;
+    /**
+     * Mark a single notification UNREAD again.
+     *
+     * 🛑 `readAt` is cleared, not left behind. It is the timestamp of a read
+     * that the caller is now saying did not happen, and a row that is
+     * `isRead: false` with a `readAt` set is a contradiction the next reader has
+     * to resolve — the digest and the unread badge key on `isRead`, so they
+     * would disagree with anything that looked at `readAt`.
+     *
+     * There was no way to do this at all: the buyer's notifications page offered
+     * only Mark-read, and the PATCH route hard-coded `markAsRead(id)` without
+     * reading a body — so a notification clicked by accident was gone from the
+     * unread list for good.
+     */
+    markAsUnread(id: string): Promise<NotificationDocument | null>;
     /**
      * Mark a single notification as read.
      */

package/dist/features/admin/repository/notification.repository.js

@@ -59,6 +59,38 @@ export class NotificationRepository extends BaseRepository {
             return 0;
         }
     }
+    /**
+     * Mark a single notification UNREAD again.
+     *
+     * 🛑 `readAt` is cleared, not left behind. It is the timestamp of a read
+     * that the caller is now saying did not happen, and a row that is
+     * `isRead: false` with a `readAt` set is a contradiction the next reader has
+     * to resolve — the digest and the unread badge key on `isRead`, so they
+     * would disagree with anything that looked at `readAt`.
+     *
+     * There was no way to do this at all: the buyer's notifications page offered
+     * only Mark-read, and the PATCH route hard-coded `markAsRead(id)` without
+     * reading a body — so a notification clicked by accident was gone from the
+     * unread list for good.
+     */
+    async markAsUnread(id) {
+        try {
+            const now = new Date();
+            await this.getCollection()
+                .doc(id)
+                .update(prepareForFirestore({
+                [NOTIFICATION_FIELDS.IS_READ]: false,
+                [NOTIFICATION_FIELDS.READ_AT]: null,
+                [NOTIFICATION_FIELDS.UPDATED_AT]: now,
+            }));
+            return this.findById(id);
+        }
+        catch (error) {
+            void normalizeError(error);
+            serverLogger.error("Failed to mark notification unread", { id, error });
+            throw error;
+        }
+    }
     /**
      * Mark a single notification as read.
      */

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/admin/schemas/action-index-form.d.ts

@@ -0,0 +1,34 @@
+import { z } from "zod";
+import type { QuickFieldDef } from "../../shell/QuickFormDrawer";
+/**
+ * 🛑 `keywords` is a COMMA-SEPARATED STRING here, not an array.
+ *
+ * `QuickFormDrawer` has no array control — its field types are text / number
+ * / select / toggle / date / textarea / email / url. Declaring `z.string()`
+ * and splitting at the call site keeps the schema honest about what the form
+ * actually produces, rather than describing a shape no control can emit.
+ * `splitKeywords` below is the one place that conversion happens.
+ */
+export declare const actionIndexOverrideSchema: z.ZodObject<{
+    label: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    keywords: z.ZodOptional<z.ZodString>;
+    weight: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    label: string;
+    weight?: number | undefined;
+    description?: string | undefined;
+    keywords?: string | undefined;
+}, {
+    label: string;
+    weight?: number | undefined;
+    description?: string | undefined;
+    keywords?: string | undefined;
+}>;
+export type ActionIndexOverrideFormInput = z.infer<typeof actionIndexOverrideSchema>;
+/** The drawer's fields, in the order an admin reads them. */
+export declare const ACTION_INDEX_OVERRIDE_FIELDS: QuickFieldDef[];
+/** The single place the comma-separated field becomes the stored array. */
+export declare function splitKeywords(raw: string | undefined): string[] | undefined;
+/** The reverse, for seeding the form from a stored override. */
+export declare function joinKeywords(keywords: readonly string[] | undefined): string;

package/dist/features/admin/schemas/action-index-form.js

@@ -0,0 +1,115 @@
+/*
+ * WHY: `/admin/action-index` told admins "Labels, descriptions and keywords
+ *      can be edited here" while offering only a Shown toggle. The server has
+ *      always accepted those fields — `ActionIndexOverride` carries `label`,
+ *      `description`, `keywords` and `weight`, and `PATCH
+ *      /api/admin/action-index` writes them through `setOverride`. The UI had
+ *      simply never grown the control, so the sentence was a promise nothing
+ *      kept.
+ *
+ * WHAT: The write contract for ONE entry override, as edited from the admin
+ *       row action.
+ *
+ * ## What is deliberately absent
+ *
+ * `href`, `kind`, `portal` and every permission field. The view's own
+ * docstring draws this line and it is the right one: repointing a built-in
+ * route is routing, and relaxing a permission is access control. Neither
+ * belongs in a quick-edit drawer beside a label.
+ *
+ * `enabled` is also absent — it has its own control in the Shown column, and
+ * a second place to set it is a second source of truth for one boolean.
+ *
+ * EXPORTS:
+ *   actionIndexOverrideSchema, ActionIndexOverrideFormInput,
+ *   ACTION_INDEX_OVERRIDE_FIELDS
+ *
+ * @tag domain:admin,search
+ * @tag layer:schema
+ * @tag pattern:none
+ * @tag access:isomorphic
+ * @tag consumers:AdminActionIndexView
+ * @tag sideEffects:none
+ */
+import { z } from "zod";
+/**
+ * 🛑 `keywords` is a COMMA-SEPARATED STRING here, not an array.
+ *
+ * `QuickFormDrawer` has no array control — its field types are text / number
+ * / select / toggle / date / textarea / email / url. Declaring `z.string()`
+ * and splitting at the call site keeps the schema honest about what the form
+ * actually produces, rather than describing a shape no control can emit.
+ * `splitKeywords` below is the one place that conversion happens.
+ */
+export const actionIndexOverrideSchema = z.object({
+    label: z
+        .string()
+        .trim()
+        .min(1, "A label is required — it is what the sidebar and search show.")
+        .max(80, "Keep labels under 80 characters so they fit the sidebar."),
+    description: z
+        .string()
+        .trim()
+        .max(200, "Keep descriptions under 200 characters.")
+        .optional(),
+    keywords: z
+        .string()
+        .trim()
+        .max(300, "Keep the keyword list under 300 characters.")
+        .optional(),
+    /*
+     * Ranking, not ordering. Higher sorts first in the search and the command
+     * palette. Bounded because an unbounded weight is how one entry ends up
+     * permanently above every other and nobody remembers why.
+     */
+    weight: z.coerce
+        .number()
+        .int("Weight must be a whole number.")
+        .min(0, "Weight cannot be negative.")
+        .max(100, "Weight is capped at 100.")
+        .optional(),
+});
+/** The drawer's fields, in the order an admin reads them. */
+export const ACTION_INDEX_OVERRIDE_FIELDS = [
+    {
+        name: "label",
+        label: "Label",
+        type: "text",
+        required: true,
+        helperText: "What the sidebar, header search and command palette show.",
+    },
+    {
+        name: "description",
+        label: "Description",
+        type: "textarea",
+        placeholder: "One line explaining what this entry is for",
+    },
+    {
+        name: "keywords",
+        label: "Keywords",
+        type: "text",
+        placeholder: "refunds, returns, money back",
+        helperText: "Comma-separated. Extra words that should find this entry in search.",
+    },
+    {
+        name: "weight",
+        label: "Weight",
+        type: "number",
+        helperText: "Higher sorts first in search results. 0–100.",
+    },
+];
+/** The single place the comma-separated field becomes the stored array. */
+export function splitKeywords(raw) {
+    if (raw === undefined)
+        return undefined;
+    const parts = raw
+        .split(",")
+        .map((part) => part.trim())
+        .filter(Boolean);
+    // An empty box means "no keywords", which is `[]` — not "leave them alone".
+    return parts;
+}
+/** The reverse, for seeding the form from a stored override. */
+export function joinKeywords(keywords) {
+    return (keywords ?? []).join(", ");
+}

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/auth/components/RegisterForm.js

@@ -11,6 +11,7 @@ import { FormShellContext, useFormShellState } from "../../../ui/forms/FormShell
 import { registerSchema, registerPasswordSchema } from "../schemas/index.js";
 import { FormErrorSummary } from "../../../ui/forms/FormErrorSummary.js";
 import { SectionForm, useSectionFormNav } from "../../shell/SectionForm.js";
+import { toUserMessage } from "../../../errors/error-display-map.js";
 const registerClientSchema = registerSchema.extend({
     displayName: z.string().min(1, "Enter your name"),
     confirmPassword: registerPasswordSchema,
@@ -81,7 +82,7 @@ export function RegisterForm({ onSubmit, isLoading = false, error, success, labe
              * email, a rejected password — which is the one thing they can act on.
              */
             const normalized = normalizeError(err);
-            setFieldError("email", normalized.message || "Registration failed");
+            setFieldError("email", toUserMessage(normalized.code, undefined, { fallback: "We couldn't create your account. Please check your details and try again." }));
         }
     };
     return (_jsx(Row, { className: `min-h-[60vh] ${className}`, align: "center", justify: "center", padding: "x-md", children: _jsxs(Stack, { className: "max-w-md w-full", gap: "lg", children: [_jsxs(Div, { className: "text-center", children: [_jsx(Row, { justify: "center", className: "mb-3", children: _jsx(SiteMark, { size: "lg" }) }), _jsx(Heading, { level: 1, className: "font-extrabold", size: "3xl", children: labels.title ?? "Create Account" }), (labels.subtitle || renderLoginLink) && (_jsxs(Text, { className: "mt-2 text-[var(--appkit-color-text-muted)]", size: "sm", children: [labels.subtitle ?? "Already have an account?", " ", renderLoginLink?.()] }))] }), success && (_jsx(Alert, { variant: "success", compact: true, children: success })), error && (_jsx(Alert, { variant: "error", compact: true, children: error })), _jsxs(FormShellContext.Provider, { value: shellCtx, children: [_jsx(FormErrorSummary, {}), _jsx(SectionForm, { sections: sections, values: values, onChange: (partial) => setValues((prev) => Object.assign({}, prev, partial)), onSubmit: handleSubmit, schema: registerClientSchema, openIds: nav.openIds, onOpenChange: nav.setOpenIds, isLoading: isLoading, submitLabel: isLoading

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/catalogue/components/CatalogueItemEditorView.js

@@ -95,11 +95,11 @@ export function CatalogueItemEditorView({ item, onSaved }) {
                     // than pointing at a photo the user has since removed.
                     onChange({ images: urls, mainImage: urls[0] ?? "" });
                 }, onUpload: handleUpload, accept: IMAGE_ACCEPT_ATTR, maxItems: 8, helperText: "Photos older than 30 days must be refreshed before this item can be listed." })),
-            categorySlugs: ({ values, onChange }) => (
+            categorySlugs: ({ values, onChange, errors }) => (
             // Explicit `<string>`: with `multiple`, `value` is `V[]`, so an
             // inferred V reads the array itself as the option type.
-            _jsx(PaginatedSelect, { multiple: true, value: values.categorySlugs, onChange: (v) => onChange({ categorySlugs: v ?? [] }), loadOptions: loadCategoryOptions, placeholder: "Search categories\u2026", searchPlaceholder: "Type a category name\u2026", noResultsText: "No categories found", ariaLabel: "Categories" })),
-            brandSlug: ({ values, onChange }) => (_jsx(PaginatedSelect, { value: values.brandSlug || null, onChange: (v) => onChange({ brandSlug: v ?? "" }), loadOptions: loadBrandOptions, placeholder: "Search brands\u2026", searchPlaceholder: "Type a brand name\u2026", noResultsText: "No brands found", ariaLabel: "Brand" })),
+            _jsx(PaginatedSelect, { multiple: true, name: "categorySlugs", error: errors.categorySlugs, value: values.categorySlugs, onChange: (v) => onChange({ categorySlugs: v ?? [] }), loadOptions: loadCategoryOptions, placeholder: "Search categories\u2026", searchPlaceholder: "Type a category name\u2026", noResultsText: "No categories found", ariaLabel: "Categories" })),
+            brandSlug: ({ values, onChange, errors }) => (_jsx(PaginatedSelect, { name: "brandSlug", error: errors.brandSlug, value: values.brandSlug || null, onChange: (v) => onChange({ brandSlug: v ?? "" }), loadOptions: loadBrandOptions, placeholder: "Search brands\u2026", searchPlaceholder: "Type a brand name\u2026", noResultsText: "No brands found", ariaLabel: "Brand" })),
         },
     }), [handleUpload]);
     const nav = useSectionFormNav(sections, form, { scope: "user:catalogue-item" });

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.