@mohasinac/appkit 4.35.2 → 4.35.4

package/dist/_internal/client/features/layout/DashboardLayoutClient.js

@@ -122,13 +122,28 @@ function useResponsiveDrawer(storageKey) {
 }
 /** Filter nav groups by navConfig (enabled toggle) + requiredPermission. */
 function filterGroups(groups, navConfig, permissions) {
-    // null permissions = admin (show everything); undefined = no filtering (backwards compat)
-    if (permissions === null && !navConfig)
+    /*
+     * `permissions === null` MEANS ADMIN, and that must hold whether or not a
+     * navConfig exists.
+     *
+     * The early return below encoded the convention correctly and then applied it
+     * only when `!navConfig`. The moment site settings carried ANY nav config,
+     * an admin fell through to `filterNavItems(..., undefined)` — and
+     * `undefined?.includes(x)` is falsy, so every item carrying a
+     * `requiredPermission` was dropped. The Admin Panel sidebar rendered empty
+     * while every admin page stayed reachable by URL.
+     *
+     * Passing `isAdmin` keeps the admin's navConfig toggles working (disabling an
+     * entry is a configuration decision, not a permission) while granting the
+     * permissions an admin implicitly holds.
+     */
+    const isAdmin = permissions === null;
+    if (isAdmin && !navConfig)
         return groups;
     return groups
         .map((group) => ({
         ...group,
-        items: filterNavItems(group.items, navConfig, permissions ?? undefined),
+        items: filterNavItems(group.items, navConfig, permissions ?? undefined, isAdmin),
     }))
         .filter((group) => group.items.length > 0);
 }

package/dist/_internal/client/features/layout/filterNavItems.d.ts

@@ -8,8 +8,29 @@ type FilterableItem = {
  * 2. requiredPermission — item hidden when user lacks the permission
  *
  * Items without an `id` always pass through (legacy / unmanaged items).
+ *
+ * 🛑 A FULL ADMIN HOLDS EVERY PERMISSION IMPLICITLY — `permissions[]` REFINES
+ * EMPLOYEES, IT DOES NOT DEFINE ADMINS.
+ *
+ * That is how the rest of the system already works: every admin route guard is
+ * `roles: ROLES_ADMIN_ONLY`, and employees are the ones who carry explicit
+ * grants (the seeded employees hold 5 and 24 permissions respectively, while
+ * `user-admin-letitrip` holds NONE — matching its seed, so this is by design
+ * rather than drift). There is no role→permission derivation anywhere in the
+ * codebase for the nav to lean on.
+ *
+ * Without `isAdmin` here, an admin matched no `requiredPermission` and EVERY
+ * admin nav item was filtered out: the Admin Panel sidebar rendered completely
+ * empty, and searching it returned "No matches". Every admin page stayed
+ * reachable by typing its URL, which is exactly what made it look cosmetic.
+ *
+ * This surfaced only recently because the check had never run: `filterNavItems`
+ * opens with `if (!item.id) return true;` and no item carried an `id` until
+ * ids were derived (see navigation.tsx). Turning a dormant check on without the
+ * data to satisfy it is the same shape as seeding a ratchet from the wrong
+ * measurement — Root Cause #84.
  */
 export declare function filterNavItems<T extends FilterableItem>(items: T[], navConfig: Record<string, {
     enabled: boolean;
-}> | undefined, userPermissions: string[] | undefined): T[];
+}> | undefined, userPermissions: string[] | undefined, isAdmin?: boolean): T[];
 export {};

package/dist/_internal/client/features/layout/filterNavItems.js

@@ -4,13 +4,38 @@
  * 2. requiredPermission — item hidden when user lacks the permission
  *
  * Items without an `id` always pass through (legacy / unmanaged items).
+ *
+ * 🛑 A FULL ADMIN HOLDS EVERY PERMISSION IMPLICITLY — `permissions[]` REFINES
+ * EMPLOYEES, IT DOES NOT DEFINE ADMINS.
+ *
+ * That is how the rest of the system already works: every admin route guard is
+ * `roles: ROLES_ADMIN_ONLY`, and employees are the ones who carry explicit
+ * grants (the seeded employees hold 5 and 24 permissions respectively, while
+ * `user-admin-letitrip` holds NONE — matching its seed, so this is by design
+ * rather than drift). There is no role→permission derivation anywhere in the
+ * codebase for the nav to lean on.
+ *
+ * Without `isAdmin` here, an admin matched no `requiredPermission` and EVERY
+ * admin nav item was filtered out: the Admin Panel sidebar rendered completely
+ * empty, and searching it returned "No matches". Every admin page stayed
+ * reachable by typing its URL, which is exactly what made it look cosmetic.
+ *
+ * This surfaced only recently because the check had never run: `filterNavItems`
+ * opens with `if (!item.id) return true;` and no item carried an `id` until
+ * ids were derived (see navigation.tsx). Turning a dormant check on without the
+ * data to satisfy it is the same shape as seeding a ratchet from the wrong
+ * measurement — Root Cause #84.
  */
-export function filterNavItems(items, navConfig, userPermissions) {
+export function filterNavItems(items, navConfig, userPermissions, isAdmin = false) {
     return items.filter((item) => {
         if (!item.id)
             return true;
+        // The admin toggle still applies to admins — disabling a nav entry is a
+        // deliberate configuration choice, not a permission the admin outranks.
         if (!(navConfig?.[item.id]?.enabled ?? true))
             return false;
+        if (isAdmin)
+            return true;
         if (item.requiredPermission && !userPermissions?.includes(item.requiredPermission))
             return false;
         return true;

package/dist/_internal/server/features/media/contextGuards.d.ts

@@ -49,5 +49,5 @@ interface GuardInput {
  * derive the SEO filename. Mirrors the inline logic that used to live
  * in /api/media/upload.
  */
-export declare function applyMediaContextGuards({ detectedMime, context: ctx, }: GuardInput): GuardResult;
+export declare function applyMediaContextGuards(input: GuardInput): GuardResult;
 export {};

package/dist/_internal/server/features/media/contextGuards.js

@@ -11,6 +11,7 @@
  */
 import { classifyMime, MIME_TO_EXT, PRODUCT_IMAGE_INDEX_MAX, PRODUCT_MAX_VIDEOS, } from "../../../shared/media/limits";
 import { generateMediaFilename, validateMediaFilename, } from "../../../../utils/id-generators";
+import { normalizeError } from "../../../../errors/normalize";
 /**
  * W1-51 — validate the generated filename before returning ok:true so a
  * malformed name can never enter signed-URL storage. Generators producing
@@ -89,7 +90,39 @@ function indexGuard(receivedIndex, max, errorMessage) {
  * derive the SEO filename. Mirrors the inline logic that used to live
  * in /api/media/upload.
  */
-export function applyMediaContextGuards({ detectedMime, context: ctx, }) {
+/*
+ * 🛑 A MISSING CONTEXT FIELD IS A 400, NEVER A 500.
+ *
+ * The filename generators slugify their inputs, and `slugify(undefined)` throws
+ * `Cannot read properties of undefined (reading 'toLowerCase')` from deep inside
+ * `id-generators`. That escaped `applyMediaContextGuards` as an unhandled throw,
+ * so `/api/media/sign` answered 500 INTERNAL — twice in production — for what is
+ * simply a caller that forgot a field. The guards below validate `index` but
+ * have never validated the string fields, and enumerating every generator's
+ * requirements here would drift from the generators themselves (Root Cause #61).
+ *
+ * So the boundary catches instead: whatever the generator needs, failing to
+ * supply it now returns an actionable 400 naming the context type, and the real
+ * message is logged rather than shown. The caller-side fix still matters — this
+ * only guarantees the failure mode is honest.
+ */
+export function applyMediaContextGuards(input) {
+    try {
+        return applyMediaContextGuardsInner(input);
+    }
+    catch (err) {
+        const normalized = normalizeError(err);
+        const message = normalized.message;
+        return {
+            ok: false,
+            status: 400,
+            error: `The upload context for "${input.context?.type ?? "unknown"}" is missing a required field. ` +
+                `Check every field its filename pattern needs.`,
+            details: { context: input.context?.type, thrown: message },
+        };
+    }
+}
+function applyMediaContextGuardsInner({ detectedMime, context: ctx, }) {
     const kind = classifyMime(detectedMime);
     if (!kind) {
         return {

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

@@ -2,13 +2,32 @@
 import { jsxs as _jsxs } from "react/jsx-runtime";
 import { Text } from "../../../ui/components/Typography";
 import { safeDisplayName } from "../../../security/pii-redact";
+/**
+ * `store-beyblade-arena` → `Beyblade Arena`.
+ *
+ * The slug fallback was described as "readable", and next to a raw Firestore id
+ * it is — but a buyer reading "by store-beyblade-arena" under a product does not
+ * see a readable name, they see a leaked identifier. Pre-order and auction
+ * documents do not denormalize `storeName`, so this fallback is what a large
+ * share of cards actually render, on every listing page.
+ *
+ * Humanising here fixes all six card variants at once and needs no data change.
+ * Denormalising `storeName` onto those documents is the better long-term fix and
+ * would simply stop this path being reached.
+ */
+function humanizeStoreSlug(slug) {
+    return slug
+        .replace(/^store-/, "")
+        .split("-")
+        .filter(Boolean)
+        .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+        .join(" ");
+}
 export function CardStoreLine({ storeName, storeId, className }) {
     if (!storeId && !storeName)
         return null;
     // `safeDisplayName` also guards the encrypted-value case: a PII-ciphertext
     // string reaching a card must render as a label, never as `enc:v1:…`.
-    // `storeId` IS the store slug in this codebase, so it is a readable last
-    // resort rather than an opaque key.
-    const seller = safeDisplayName(storeName, storeId ?? "Seller");
+    const seller = safeDisplayName(storeName, storeId ? humanizeStoreSlug(storeId) : "Seller");
     return (_jsxs(Text, { className: className ?? "mt-0.5 text-[11px]", color: "faint", children: ["by ", seller] }));
 }

package/dist/features/products/hooks/useProducts.js

@@ -3,6 +3,8 @@ import { useEffect } from "react";
 import { useQuery } from "@tanstack/react-query";
 import { apiClient } from "../../../http";
 import { useToast } from "../../../ui";
+import { useOptionalSession } from "../../../react/contexts/SessionContext";
+import { isAdminUser, isTesterUser } from "../../auth/role-predicates";
 import { PRODUCT_ENDPOINTS } from "../../../constants/api-endpoints";
 export function useProducts(params = {}, opts) {
     const { showToast } = useToast();
@@ -73,11 +75,46 @@ export function useProducts(params = {}, opts) {
             sp.set(key, value);
     }
     const qs = sp.toString();
+    /*
+     * 🛑 A TESTER MUST REFETCH; EVERYONE ELSE MUST KEEP THE CACHED SSR PAINT.
+     *
+     * Sandbox rows are correctly hidden from the public. But the SSR listing views
+     * pass no `viewer` to `listPublicProducts`, so the server-rendered grid is the
+     * anonymous one for EVERY visitor — and with `initialData` + `staleTime:
+     * Infinity` the client never refetches, so a signed-in tester saw a catalogue
+     * with no sandbox fixtures in it, on every listing page. The items were
+     * reachable by direct URL, which is what made it look like a data problem
+     * rather than a visibility one.
+     *
+     * The fix is NOT to read the session in those SSR views. `getServerSessionUser`
+     * is a dynamic API, and calling it there would make every public listing page
+     * per-request — no caching, a billed invocation per visitor, and every
+     * `revalidate` silently overridden. That is Root Cause #82, and paying it for a
+     * testing affordance would be a poor trade.
+     *
+     * `/api/products` ALREADY resolves the session and passes `viewer`. So the only
+     * thing missing was a reason for the client to ask again: the query key now
+     * carries the viewer class, giving testers their own cache entry, and their
+     * `staleTime` is not frozen. Anonymous visitors keep the cached SSR data
+     * untouched and issue no extra request.
+     *
+     * `useOptionalSession` rather than `useAuth()` on purpose — `useSession`
+     * THROWS outside a provider, and making a public appkit hook require one would
+     * be a breaking contract change (Root Cause #20). Absent provider degrades to
+     * "not a tester", which is the fail-closed answer.
+     */
+    const session = useOptionalSession();
+    const viewer = session?.user;
+    const canSeeTestData = isTesterUser(viewer) || isAdminUser(viewer);
     const query = useQuery({
-        queryKey: ["products", qs],
+        queryKey: ["products", qs, canSeeTestData ? "with-test-data" : "public"],
         queryFn: () => apiClient.get(`${PRODUCT_ENDPOINTS.LIST}${qs ? `?${qs}` : ""}`),
-        initialData: opts?.initialData,
-        staleTime: opts?.staleTime ?? (opts?.initialData != null ? Infinity : 0),
+        // The SSR paint is the anonymous view, so it is only a valid starting point
+        // for an anonymous viewer. Handing it to a tester would show them the very
+        // rows this refetch exists to reveal.
+        initialData: canSeeTestData ? undefined : opts?.initialData,
+        staleTime: opts?.staleTime ??
+            (!canSeeTestData && opts?.initialData != null ? Infinity : 0),
         enabled: opts?.enabled,
     });
     const warning = query.data?.warning;

package/dist/features/seller/components/SellerProductShell.js

@@ -147,6 +147,13 @@ function StepMedia({ values, onChange, storeSlug = "store", }) {
                 }), onChangeField: (media) => onChange({ video: media ?? undefined }), onThumbnailChange: (thumbnailUrl) => onChange({ video: values.video ? { ...values.video, thumbnailUrl } : undefined }), onDurationChange: (duration) => onChange({ video: values.video ? { ...values.video, duration } : undefined }), onUpload: (file) => upload(file, "products", true, {
                     type: "product-video",
                     name: values.title ?? "product",
+                    // `category` is REQUIRED — generateProductVideoFilename slugifies it,
+                    // and slugify(undefined) threw `Cannot read properties of undefined
+                    // (reading 'toLowerCase')` inside the generator, surfacing as a 500
+                    // from /api/media/sign. Every product video upload from this panel
+                    // failed that way; ProductForm's gallery path passed it and worked,
+                    // which is why only the dedicated video tab was broken.
+                    category: values.category || "uncategorized",
                     store: storeSlug,
                 }), kind: "auto", helperText: "The gallery above accepts a video file directly. Use this panel for a YouTube or external URL, or to trim and pick a poster frame." }), _jsx(FormField, { name: "externalVideoUrl", label: "3rd-party video URL (YouTube / Vimeo)", type: "text", value: values.externalVideoUrl ?? "", onChange: (v) => onChange({ externalVideoUrl: v }), placeholder: "https://www.youtube.com/watch?v=\u2026", hint: "External video links are queued for moderation and become visible to buyers after admin approval." }), _jsx(FormField, { name: "youtubeId", label: "YouTube Video ID (optional)", type: "text", value: values.youtubeId ?? "", onChange: (v) => onChange({ youtubeId: v }), placeholder: "e.g. dQw4w9WgXcQ", helpText: "Paste the 11-character ID from the YouTube URL" })] }));
 }

package/dist/features/tester/seed-data/authored/seo__page-metadata.js

@@ -95,14 +95,14 @@ export const authored = {
         startPage: "/products",
         steps: [
             "Open the network panel and navigate to a product path whose trailing segment is a nonsense word no listing uses.",
-            "Read the status code of the document response.",
             "Read what the page shows.",
-            "View the source and look for a robots meta tag.",
-            "Repeat with a nonsense store path and a nonsense category path.",
+            "View the source and read every robots meta tag.",
+            "Repeat with a nonsense store path and a nonsense auction path.",
+            "Open a REAL product page and read its robots meta tags too.",
         ],
-        expectedBehaviour: "A missing page returns 404 and marks itself not-indexable. A 200 carrying a 'not found' message is a soft 404 — the URL stays in the index indefinitely, and every mistyped link a crawler follows adds another.",
-        expectedUiState: "The document response is 404 on all three paths, the page shows a readable not-found state with a route onward, and it is marked not-indexable. A 200 status is the finding regardless of what the body says.",
-        expectedData: { statusCode: 404 },
+        expectedBehaviour: "A missing page renders the site's 404 view and marks itself NOINDEX. Judge the noindex, not the status code: Next streams the response, so the headers are already sent by the time the not-found is raised and the status can no longer be changed. It injects a noindex robots tag into the streamed HTML instead, and that is what actually keeps the URL out of the index. A 200 here is expected and is not the finding.",
+        expectedUiState: "All three missing paths render the 404 view and their source carries a robots tag whose content is noindex. The real product page carries no noindex — check it, because a blanket noindex would satisfy the first half while quietly de-indexing the whole catalogue.",
+        expectedData: { missingPageIsNoindex: true, realPageIsNoindex: false },
         endResult: "Read-only.",
     },
     "checklist-seo-page-metadata-title-length-reasonable": {

package/dist/react/contexts/SessionContext.d.ts

@@ -95,6 +95,19 @@ export interface SessionProviderProps {
 }
 export declare function SessionProvider({ children, initialUser, endpoints: endpointOverrides, onSignOutInvalidate, signOutInvalidationKeys, }: SessionProviderProps): React.JSX.Element;
 export declare function useSession(): SessionContextValue;
+/**
+ * The session if a provider is mounted, `null` if not — never throws.
+ *
+ * `useSession` throwing is right for a component that genuinely cannot work
+ * signed-out. It is wrong for library code that merely wants to ADJUST for the
+ * viewer, because requiring a provider there turns an optional refinement into a
+ * breaking contract change for every consumer (Root Cause #20).
+ *
+ * Use this only where "no provider" has a sensible, fail-closed answer — e.g.
+ * `useProducts`, which treats an absent session as "not a tester" and keeps the
+ * public cached view.
+ */
+export declare function useOptionalSession(): SessionContextValue | null;
 export declare function useAuth(): {
     user: SessionUser | null;
     loading: boolean;

package/dist/react/contexts/SessionContext.js

@@ -394,6 +394,21 @@ export function useSession() {
     }
     return context;
 }
+/**
+ * The session if a provider is mounted, `null` if not — never throws.
+ *
+ * `useSession` throwing is right for a component that genuinely cannot work
+ * signed-out. It is wrong for library code that merely wants to ADJUST for the
+ * viewer, because requiring a provider there turns an optional refinement into a
+ * breaking contract change for every consumer (Root Cause #20).
+ *
+ * Use this only where "no provider" has a sensible, fail-closed answer — e.g.
+ * `useProducts`, which treats an absent session as "not a tester" and keeps the
+ * public cached view.
+ */
+export function useOptionalSession() {
+    return useContext(SessionContext) ?? null;
+}
 export function useAuth() {
     const { user, loading, refreshUser } = useSession();
     return { user, loading, refreshUser };

package/dist/ui/components/ImageLightbox.js

@@ -83,7 +83,26 @@ export function ImageLightbox({ images, activeIndex, onClose, onNavigate, showTh
         adjustZoom(e.deltaY < 0 ? ZOOM_STEP : -ZOOM_STEP);
     }, [adjustZoom]);
     const handleKeyDown = useCallback((e) => {
+        /*
+         * Escape unwinds ONE level: fullscreen first, the lightbox second.
+         *
+         * Unconditionally calling `onClose()` meant Escape in fullscreen tore the
+         * whole lightbox down while the browser was natively exiting fullscreen at
+         * the same moment — the user asked to leave fullscreen and lost the image
+         * they were looking at. The Exit-fullscreen BUTTON behaved correctly, which
+         * is what made this read as a keyboard quirk rather than a bug.
+         *
+         * Exiting explicitly rather than relying on the browser's own handling: the
+         * `fullscreenchange` listener above is what clears `isFullscreen`, so going
+         * through the same path keeps the button label and this state in agreement
+         * whichever way the user leaves.
+         */
         if (e.key === "Escape") {
+            if (isFullscreen) {
+                const doc = document;
+                (document.exitFullscreen?.() ?? doc.webkitExitFullscreen?.())?.catch?.(() => { });
+                return;
+            }
             onClose();
             return;
         }
@@ -112,7 +131,11 @@ export function ImageLightbox({ images, activeIndex, onClose, onNavigate, showTh
             setRotation(0);
             return;
         }
-    }, [onClose, navigate, adjustZoom]);
+    }, 
+    // `isFullscreen` is a real dependency now — Escape branches on it, and a
+    // stale closure would send the user back to the pre-fix behaviour exactly
+    // when they are in fullscreen.
+    [onClose, navigate, adjustZoom, isFullscreen]);
     // Focus overlay on open for keyboard to work
     useEffect(() => {
         if (isOpen)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mohasinac/appkit",
-  "version": "4.35.2",
+  "version": "4.35.4",
   "license": "MIT",
   "publishConfig": {
     "access": "public"