@usequeek/theme-kit 0.1.8 → 0.1.9

package/api/shop.ts

@@ -0,0 +1,26 @@
+import { createServerStoreClient, getRequestOrigin } from '../sdk/server-store-client';
+import type { ApiResponse } from '../types/product';
+import { parseShopResponse, shopRequestParams, type ShopPrefetch, type ShopQuery } from '../utils/shop-query';
+
+/**
+ * The shop page's first page of products, fetched while the server renders
+ * `/shop`, for `ShopPrefetchProvider` to hand to `useShop` — so the product grid
+ * is in the HTML instead of appearing after the browser has run the JS and
+ * fetched it (kili-foods' `/shop` main content landed at 2.8 s that way).
+ *
+ * Same request and the same parsing as the browser's `useShop` (both come from
+ * utils/shop-query). Reads go through `/client/store/*` like every SSR read, so
+ * pricing is the storefront's, never the marketplace's.
+ *
+ * Returns null on ANY failure: the page must never break over a head start —
+ * `useShop` then fetches in the browser exactly as it did before.
+ */
+export async function fetchShopPrefetch(vendorSlug: string, query: ShopQuery): Promise<ShopPrefetch | null> {
+  try {
+    const client = createServerStoreClient(vendorSlug, await getRequestOrigin());
+    const response = await client.get<ApiResponse<unknown, Record<string, unknown>>>('/products', shopRequestParams(query));
+    return { query, ...parseShopResponse(response, query) };
+  } catch {
+    return null;
+  }
+}

package/apps/follow-card.tsx

@@ -6,6 +6,7 @@ import { useStorefront } from '../provider';
 import { useUserStore } from '../stores/user-store';
 import { useAuthModalStore } from '../stores/auth-modal-store';
 import { getQueekClient } from '../sdk/queek-client';
+import { formatCount } from '../utils/format';
 
 interface FollowData {
   following: boolean;
@@ -165,7 +166,7 @@ export function FollowCard({ display }: { display?: 'floating' | 'inline' } = {}
           </p>
           {followersCount > 0 && (
             <p className="core-follow-card__count">
-              {followersCount.toLocaleString()} {followersCount === 1 ? 'follower' : 'followers'}
+              {formatCount(followersCount)} {followersCount === 1 ? 'follower' : 'followers'}
             </p>
           )}
         </div>

package/components/blog/post-meta.tsx

@@ -4,13 +4,16 @@ import type { JSX } from 'react';
 import type { Post } from '../../types/page';
 import { useStorefront } from '../../provider';
 import { Image } from '../image';
+import { formatDisplayDate } from '../../utils/format';
 
 function formatDate(value: string): string {
   const date = new Date(value);
   if (Number.isNaN(date.getTime())) {
     return '';
   }
-  return date.toLocaleDateString('en-US', { year: 'numeric', month: 'long', day: 'numeric' });
+  // en-US long form as before; the fixed zone keeps a post published near midnight
+  // UTC on the same day on the server and in the browser.
+  return formatDisplayDate(date, { year: 'numeric', month: 'long', day: 'numeric' }, 'en-US');
 }
 
 /**

package/components/image.tsx

@@ -129,9 +129,20 @@ export function Image({ fallback, placeholder, variants, intent = 'raw', onError
     effectiveSizes = undefined;
   }
 
+  // Cards sit in grids and rails, mostly below the fold — and a card's hover
+  // image is invisible until hover. Eager, a server-rendered grid of 24 cards
+  // made React preload the first ~10 (also into the 103 Early Hints header) and
+  // fetch every image at once, racing the page's render-blocking CSS: /shop's
+  // first paint went 1.8 s → 2.9 s on Slow 4G (24/9/26). Lazy is next/image's
+  // default as well. A theme whose card IS the page's main image passes
+  // loading="eager" or fetchPriority="high".
+  const lazyByDefault = (intent === 'card' || intent === 'card2x') && props.fetchPriority !== 'high';
+  const loading = props.loading ?? (lazyByDefault ? 'lazy' : undefined);
+
   return (
     <img
       {...props}
+      loading={loading}
       src={effectiveSrc}
       srcSet={effectiveSrcSet}
       sizes={effectiveSizes}

package/components/product-metafields.tsx

@@ -5,6 +5,7 @@ import type {
   MetaobjectEntry,
   Product,
 } from '../types/product';
+import { formatDisplayDate } from '../utils/format';
 
 export interface ProductMetafieldDefinitionLabels {
   [key: string]: { name: string; type: string };
@@ -106,7 +107,7 @@ function renderScalar(value: MetafieldScalar, key: string, label: string, type:
     const time = new Date(text).getTime();
     return (
       <p className="core-metafields__text">
-        {Number.isNaN(time) ? text : new Date(time).toLocaleDateString()}
+        {Number.isNaN(time) ? text : formatDisplayDate(time, {})}
       </p>
     );
   }

package/hooks/use-shop-params.ts

@@ -2,9 +2,7 @@
 
 import { useCallback } from 'react';
 import { usePathname, useRouter, useSearchParams } from 'next/navigation';
-import type { ShopSort } from './use-shop';
-
-const SORTS: ShopSort[] = ['latest', 'popular', 'price_low', 'price_high'];
+import { parseShopSearchParams, type ShopSort } from '../utils/shop-query';
 
 export interface ShopParams {
   categorySlug: string | null;
@@ -29,12 +27,8 @@ export function useShopParams(): ShopParams {
   const pathname = usePathname();
   const searchParams = useSearchParams();
 
-  const categorySlug = searchParams.get('category');
-  const keyword = searchParams.get('q') ?? '';
-  const sortRaw = searchParams.get('sort');
-  const sort: ShopSort = SORTS.includes(sortRaw as ShopSort) ? (sortRaw as ShopSort) : 'latest';
-  const pageRaw = Number(searchParams.get('page'));
-  const page = Number.isFinite(pageRaw) && pageRaw > 1 ? Math.floor(pageRaw) : 1;
+  // Shared with the server's /shop prefetch, so both read the URL identically.
+  const { categorySlug, keyword, sort, page } = parseShopSearchParams((key) => searchParams.get(key));
 
   const apply = useCallback(
     (next: { category?: string | null; q?: string | null; sort?: ShopSort; page?: number }) => {

package/hooks/use-shop.ts

@@ -1,33 +1,47 @@
 'use client';
 
-import { useEffect, useMemo, useRef, useState } from 'react';
+import { createContext, createElement, useContext, useEffect, useMemo, useRef, useState, type JSX, type ReactNode } from 'react';
 import { useStorefront } from '../provider';
-import type { Product, ApiResponse, LegacyProductLike } from '../types/product';
+import type { Product, ApiResponse } from '../types/product';
 import { createBrowserClient } from '../sdk/client';
-import { extractProducts, normalizeProduct } from '../utils/product-normalizer';
-
-export type ShopSort = 'latest' | 'popular' | 'price_low' | 'price_high';
-
-export interface ShopPagination {
-  currentPage: number;
-  lastPage: number;
-  perPage: number;
-  total: number;
-  from: number | null;
-  to: number | null;
-  hasMore: boolean;
-}
+import {
+  SHOP_DEFAULT_PER_PAGE,
+  normalizeShopQuery,
+  parseShopResponse,
+  sameShopQuery,
+  shopRequestParams,
+  type ShopPagination,
+  type ShopPrefetch,
+  type ShopSort,
+} from '../utils/shop-query';
+
+// Types live in utils/shop-query (shared with the server fetch); re-exported so
+// every existing `import type { ShopSort } from '.../hooks/use-shop'` keeps working.
+export type { ShopPagination, ShopPrefetch, ShopQuery, ShopSort } from '../utils/shop-query';
 
 const EMPTY_PAGINATION: ShopPagination = {
   currentPage: 1,
   lastPage: 1,
-  perPage: 24,
+  perPage: SHOP_DEFAULT_PER_PAGE,
   total: 0,
   from: null,
   to: null,
   hasMore: false,
 };
 
+const ShopPrefetchContext = createContext<ShopPrefetch | null>(null);
+
+/**
+ * Hands `useShop` a page the server already fetched (`fetchShopPrefetch`), so
+ * the product grid renders in the server HTML. A `useShop` call uses it only
+ * when its query matches exactly — same filters, sort, page and page size —
+ * and otherwise fetches as it always has. Themes never touch it; the storefront
+ * wraps its `/shop` route.
+ */
+export function ShopPrefetchProvider({ value, children }: { value: ShopPrefetch | null; children: ReactNode }): JSX.Element {
+  return createElement(ShopPrefetchContext.Provider, { value }, children);
+}
+
 function sortProducts(list: Product[], sort: ShopSort): Product[] {
   const copy = [...list];
   switch (sort) {
@@ -85,23 +99,27 @@ export function useShop(options?: {
   pagination: ShopPagination;
 } {
   const { vendor, previewData } = useStorefront();
+  const prefetch = useContext(ShopPrefetchContext);
 
-  const perPage = options?.perPage ?? 24;
+  const perPage = options?.perPage ?? SHOP_DEFAULT_PER_PAGE;
   const categorySlug = options?.categorySlug ?? null;
   const keyword = options?.keyword ?? null;
   const sort = options?.sort ?? 'latest';
   const page = options?.page && options.page > 0 ? options.page : 1;
+  const query = normalizeShopQuery({ categorySlug, keyword, sort, page, perPage });
 
   const previewProducts = previewData?.products;
   const isPreview = Array.isArray(previewProducts);
 
-  const [products, setProducts] = useState<Product[]>([]);
-  const [isLoading, setIsLoading] = useState(!isPreview);
-  const [pagination, setPagination] = useState<ShopPagination>({
-    ...EMPTY_PAGINATION,
-    perPage,
-  });
-  const cancelRef = useRef<boolean>(false);
+  // The server's page, when it is exactly this query (see ShopPrefetchProvider).
+  const seed = !isPreview && prefetch && sameShopQuery(prefetch.query, query) ? prefetch : null;
+
+  const [products, setProducts] = useState<Product[]>(seed?.products ?? []);
+  const [isLoading, setIsLoading] = useState(!isPreview && !seed);
+  const [pagination, setPagination] = useState<ShopPagination>(seed?.pagination ?? { ...EMPTY_PAGINATION, perPage });
+  // The query whose results are already in state. Seeded with the prefetch so
+  // the first effect run does not refetch the page the server just rendered.
+  const loadedQueryRef = useRef<string | null>(seed ? JSON.stringify(seed.query) : null);
 
   // Preview: derive everything synchronously from the demo catalogue.
   const previewResult = useMemo(() => {
@@ -130,53 +148,47 @@ export function useShop(options?: {
   }, [isPreview, previewProducts, categorySlug, keyword, sort, page, perPage]);
 
   // Production: fetch the live catalogue.
+  const queryKey = JSON.stringify(query);
   useEffect(() => {
     if (isPreview) return undefined;
+    // Already showing this query — the server's prefetch, or a fetch that
+    // finished. (Clear any loading state a cancelled in-between query left.)
+    if (loadedQueryRef.current === queryKey) {
+      setIsLoading(false);
+      return undefined;
+    }
 
-    cancelRef.current = false;
+    // Per-run flag: a shared ref let a slow earlier fetch (filters A) land after
+    // a newer one (filters B) had reset it, overwriting B's products.
+    let cancelled = false;
     setIsLoading(true);
 
     const client = createBrowserClient(vendor.slug ?? undefined);
-    const query: Record<string, string | number> = { per_page: perPage, page };
-    if (categorySlug) query.category_slug = categorySlug;
-    if (keyword?.trim()) query.keyword = keyword.trim();
-    if (sort) query.sort = sort;
+    const current = JSON.parse(queryKey) as typeof query;
 
     async function run(): Promise<void> {
       try {
         const response = await client.get<ApiResponse<unknown, Record<string, unknown>>>(
           '/products',
-          query,
-        );
-        if (cancelRef.current) return;
-
-        const meta = (response.meta ?? {}) as Record<string, unknown>;
-        const nestedMeta = (meta.pagination ?? meta) as Record<string, unknown>;
-        setPagination({
-          currentPage: (nestedMeta.current_page as number) ?? page,
-          lastPage: (nestedMeta.last_page as number) ?? 1,
-          perPage: (nestedMeta.per_page as number) ?? perPage,
-          total: (nestedMeta.total as number) ?? 0,
-          from: (nestedMeta.from as number | null) ?? null,
-          to: (nestedMeta.to as number | null) ?? null,
-          hasMore: (nestedMeta.has_more as boolean) ?? false,
-        });
-        setProducts(
-          extractProducts(response.data).map((item) =>
-            normalizeProduct(item as LegacyProductLike),
-          ),
+          shopRequestParams(current),
         );
+        if (cancelled) return;
+
+        const parsed = parseShopResponse(response, current);
+        setPagination(parsed.pagination);
+        setProducts(parsed.products);
+        loadedQueryRef.current = queryKey;
       } finally {
-        if (!cancelRef.current) setIsLoading(false);
+        if (!cancelled) setIsLoading(false);
       }
     }
 
     void run();
 
     return () => {
-      cancelRef.current = true;
+      cancelled = true;
     };
-  }, [isPreview, vendor.slug, categorySlug, keyword, sort, perPage, page]);
+  }, [isPreview, vendor.slug, queryKey]);
 
   if (isPreview && previewResult) {
     return { products: previewResult.products, isLoading: false, pagination: previewResult.pagination };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usequeek/theme-kit",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "private": false,
   "license": "MIT",
   "description": "The framework a Queek storefront theme is built against.",

package/page-renderer.tsx

@@ -58,13 +58,25 @@ class DraftSectionBoundary extends Component<
   }
 }
 
+/** JSON.stringify replacer that drops promises/thenables and functions. */
+function signatureReplacer(_key: string, value: unknown): unknown {
+  if (typeof value === 'function') return undefined;
+  if (value !== null && typeof value === 'object' && typeof (value as { then?: unknown }).then === 'function') return undefined;
+  return value;
+}
+
 export function PageRenderer({ blocks }: { blocks: Block[] }): JSX.Element {
   const draftBlocks = useEditPreviewStore((state) => state.blocks);
   const reconcileDraftBlocks = useEditPreviewStore((state) => state.reconcile);
 
   // A new server payload is authoritative — drop the streamed draft so the
   // debounced save reconciles and a drifted preview cannot outlive a refresh.
-  const serverSignature = useMemo(() => JSON.stringify(blocks), [blocks]);
+  // Fingerprint of the page DATA only. Blocks can carry values that are not data:
+  // the storefront attaches streamed `productsPromise`/`metaobjectsPromise`, which
+  // arrive here as React Flight thenables referencing the whole RSC response —
+  // stringifying those threw "Converting circular structure to JSON" during
+  // server rendering (dev) and serialised Flight internals on every render (prod).
+  const serverSignature = useMemo(() => JSON.stringify(blocks, signatureReplacer), [blocks]);
   useEffect(() => {
     reconcileDraftBlocks();
   }, [serverSignature, reconcileDraftBlocks]);

package/shared-blocks/product-qa.tsx

@@ -8,6 +8,7 @@ import { useProductQuestions } from '../hooks/use-product-questions';
 import { useAuth } from '../hooks/use-auth';
 import { useStorefront } from '../provider';
 import { getQueekClient } from '../sdk/queek-client';
+import { formatDisplayDate } from '../utils/format';
 
 const MAX_QUESTION_LENGTH = 1000;
 
@@ -192,13 +193,6 @@ function initialsFor(name: string): string {
 }
 
 function formatDate(iso: string): string {
-  try {
-    return new Date(iso).toLocaleDateString(undefined, {
-      month: 'short',
-      day: 'numeric',
-      year: 'numeric',
-    });
-  } catch {
-    return '';
-  }
+  // Fixed locale + zone: this block renders on the server too (see formatDisplayDate).
+  return formatDisplayDate(iso);
 }

package/shared-blocks/reviews.tsx

@@ -6,6 +6,7 @@ import type { ReviewItem, ReviewsBlockData, ReviewsSummary } from '../types/bloc
 import { Image } from '../components/image';
 import { useReviews } from '../hooks/use-reviews';
 import { useStorefront } from '../provider';
+import { formatDisplayDate } from '../utils/format';
 
 /**
  * Framework-owned reviews block. Renders verified, platform-generated reviews
@@ -425,13 +426,6 @@ function initialsFor(name: string): string {
 }
 
 function formatDate(iso: string): string {
-  try {
-    return new Date(iso).toLocaleDateString(undefined, {
-      month: 'short',
-      day: 'numeric',
-      year: 'numeric',
-    });
-  } catch {
-    return '';
-  }
+  // Fixed locale + zone: this block renders on the server too (see formatDisplayDate).
+  return formatDisplayDate(iso);
 }

package/tests/display-format.test.ts

@@ -0,0 +1,49 @@
+import { readFileSync, readdirSync, statSync } from 'node:fs';
+import { join, relative, resolve } from 'node:path';
+import { describe, expect, it } from 'vitest';
+import { DISPLAY_LOCALE, DISPLAY_TIME_ZONE, formatCount, formatDisplayDate, formatMoney } from '../utils/format';
+
+/**
+ * Storefront pages render on the server first. A date formatted with the
+ * runtime's default locale printed "Feb 14, 2026" on the server (Node: en-US,
+ * UTC) and "14 Feb 2026" in a Nigerian browser; React then failed hydration
+ * (#418) and re-rendered the whole page on the client — seen live on every
+ * store page with a reviews block. Everything the kit displays is formatted in
+ * one fixed locale and zone instead.
+ */
+describe('display formatting is the same on the server and in the browser', () => {
+  it('uses one fixed locale and zone', () => {
+    expect(DISPLAY_LOCALE).toBe('en-NG');
+    expect(DISPLAY_TIME_ZONE).toBe('Africa/Lagos');
+  });
+
+  it('formats dates in Lagos time, whatever the machine is set to', () => {
+    expect(formatDisplayDate('2026-02-14T10:00:00Z')).toBe('14 Feb 2026');
+    // 23:30 UTC is already the 15th in Lagos (UTC+1) — the server (UTC) and the
+    // browser (Lagos) used to print different days for this review.
+    expect(formatDisplayDate('2026-02-14T23:30:00Z')).toBe('15 Feb 2026');
+    expect(formatDisplayDate('2026-02-14', {})).toBe('14/02/2026');
+    expect(formatDisplayDate('2026-02-14T23:30:00Z', { year: 'numeric', month: 'long', day: 'numeric' }, 'en-US')).toBe('February 15, 2026');
+    expect(formatDisplayDate('not a date')).toBe('');
+  });
+
+  it('formats counts and money with fixed grouping', () => {
+    expect(formatCount(1234567)).toBe('1,234,567');
+    expect(formatMoney(12500)).toBe('₦12,500');
+  });
+
+  it('no kit source formats with the runtime default locale', () => {
+    const ROOT = resolve(__dirname, '..');
+    const walk = (dir: string): string[] => readdirSync(dir).flatMap((entry) => {
+      const path = join(dir, entry);
+      if (entry === 'node_modules' || entry === 'tests' || entry.startsWith('.')) return [];
+      if (statSync(path).isDirectory()) return walk(path);
+      return /\.(ts|tsx)$/.test(entry) ? [path] : [];
+    });
+    const offenders = walk(ROOT).flatMap((file) => {
+      const source = readFileSync(file, 'utf8');
+      return /\.toLocale(?:Date|Time)?String\(\s*(?:undefined\s*[,)]|\))/.test(source) ? [relative(ROOT, file)] : [];
+    });
+    expect(offenders).toEqual([]);
+  });
+});

package/tests/image-loading.test.tsx

@@ -0,0 +1,31 @@
+import type { JSX } from 'react';
+import { renderToStaticMarkup } from 'react-dom/server';
+import { describe, expect, it } from 'vitest';
+import { Image } from '../components/image';
+
+/**
+ * Card images are lazy by default. Server-rendered product grids (the /shop
+ * prefetch, streamed product blocks) otherwise made React preload the first
+ * ~10 card images and fetch all of them at once, racing the page's CSS — /shop
+ * first paint 1.8 s → 2.9 s on Slow 4G. Heroes and everything else unchanged.
+ */
+describe('Image loading defaults', () => {
+  const html = (el: JSX.Element) => renderToStaticMarkup(el);
+
+  it('lazy-loads card images by default', () => {
+    expect(html(<Image src="/p.jpg" alt="" intent="card" />)).toContain('loading="lazy"');
+    expect(html(<Image src="/p.jpg" alt="" intent="card2x" />)).toContain('loading="lazy"');
+  });
+
+  it('respects an explicit choice, and fetchPriority="high"', () => {
+    expect(html(<Image src="/p.jpg" alt="" intent="card" loading="eager" />)).toContain('loading="eager"');
+    expect(html(<Image src="/p.jpg" alt="" intent="card" fetchPriority="high" />)).not.toContain('loading=');
+  });
+
+  it('leaves heroes, avatars and untyped images as they were', () => {
+    for (const intent of ['hero', 'avatar', 'modal', 'raw'] as const) {
+      expect(html(<Image src="/p.jpg" alt="" intent={intent} />)).not.toContain('loading=');
+    }
+    expect(html(<Image src="/p.jpg" alt="" />)).not.toContain('loading=');
+  });
+});

package/tests/page-renderer-signature.test.tsx

@@ -0,0 +1,42 @@
+import { renderToStaticMarkup } from 'react-dom/server';
+import { describe, expect, it } from 'vitest';
+import { StorefrontContext } from '../provider';
+import { ThemeProvider } from '../theme-context';
+import { PageRenderer } from '../page-renderer';
+import type { Block } from '../types/block';
+import type { ThemeModule } from '../types/theme';
+
+/**
+ * The storefront attaches streamed `productsPromise` / `metaobjectsPromise` to
+ * page blocks. On the server they arrive as React Flight thenables that point
+ * back at the whole RSC response. PageRenderer's change-detection signature
+ * JSON-stringified the blocks, and that threw "Converting circular structure to
+ * JSON" during server rendering — every real store with a products block fell
+ * back to client-only rendering in `next dev`.
+ */
+
+function circularThenable(): unknown {
+  const response: Record<string, unknown> = { _chunks: new Map() };
+  response._weakResponse = { response };
+  return { status: 'pending', value: null, reason: response, then: () => undefined };
+}
+
+describe('PageRenderer', () => {
+  it('server-renders blocks that carry a streamed (circular) promise', () => {
+    const blocks = [
+      { type: 'content', data: { markdown: 'Fresh meals, delivered' }, productsPromise: circularThenable(), metaobjectsPromise: circularThenable() },
+    ] as unknown as Block[];
+    const theme = { getBlock: () => () => null } as unknown as ThemeModule;
+    const store = { vendor: { id: 'v1', slug: 'kili-foods' }, config: {}, menus: [], basePath: '', pagesChrome: {} };
+
+    const html = renderToStaticMarkup(
+      <StorefrontContext.Provider value={store as never}>
+        <ThemeProvider theme={theme}>
+          <PageRenderer blocks={blocks} />
+        </ThemeProvider>
+      </StorefrontContext.Provider>,
+    );
+
+    expect(html).toContain('Fresh meals, delivered');
+  });
+});

package/tests/shop-query.test.ts

@@ -0,0 +1,58 @@
+import { describe, expect, it } from 'vitest';
+import {
+  SHOP_DEFAULT_PER_PAGE,
+  normalizeShopQuery,
+  parseShopResponse,
+  parseShopSearchParams,
+  sameShopQuery,
+  shopRequestParams,
+} from '../utils/shop-query';
+
+/**
+ * The server's /shop prefetch only saves the browser a fetch when both sides
+ * build the same query — these are the rules both share.
+ */
+describe('shop query (shared by useShop and the server prefetch)', () => {
+  it('applies the same defaults useShop always has', () => {
+    expect(normalizeShopQuery()).toEqual({ categorySlug: null, keyword: null, sort: 'latest', page: 1, perPage: SHOP_DEFAULT_PER_PAGE });
+    expect(SHOP_DEFAULT_PER_PAGE).toBe(24);
+  });
+
+  it('treats a blank or padded keyword like the request does', () => {
+    expect(normalizeShopQuery({ keyword: '   ' }).keyword).toBeNull();
+    expect(normalizeShopQuery({ keyword: '  rice ' }).keyword).toBe('rice');
+    expect(sameShopQuery(normalizeShopQuery({ keyword: '' }), normalizeShopQuery({ keyword: null }))).toBe(true);
+  });
+
+  it('distinguishes every field that changes the page fetched', () => {
+    const base = normalizeShopQuery({ categorySlug: 'soups', keyword: 'egusi', sort: 'popular', page: 2, perPage: 24 });
+    for (const change of [{ categorySlug: 'rice' }, { keyword: 'okra' }, { sort: 'price_low' as const }, { page: 3 }, { perPage: 8 }]) {
+      expect(sameShopQuery(base, normalizeShopQuery({ ...base, ...change }))).toBe(false);
+    }
+    expect(sameShopQuery(base, normalizeShopQuery({ ...base }))).toBe(true);
+  });
+
+  it('reads the /shop URL exactly as useShopParams always has', () => {
+    const read = (qs: string) => parseShopSearchParams((key) => new URLSearchParams(qs).get(key));
+    expect(read('')).toEqual({ categorySlug: null, keyword: '', sort: 'latest', page: 1 });
+    expect(read('category=soups&q=egusi&sort=price_high&page=3')).toEqual({ categorySlug: 'soups', keyword: 'egusi', sort: 'price_high', page: 3 });
+    expect(read('sort=cheapest&page=0').sort).toBe('latest');
+    expect(read('page=abc').page).toBe(1);
+    expect(read('page=2.7').page).toBe(2);
+  });
+
+  it('sends the params the storefront products endpoint expects', () => {
+    expect(shopRequestParams(normalizeShopQuery())).toEqual({ per_page: 24, page: 1, sort: 'latest' });
+    expect(shopRequestParams(normalizeShopQuery({ categorySlug: 'soups', keyword: ' egusi ', sort: 'popular', page: 2 })))
+      .toEqual({ per_page: 24, page: 2, category_slug: 'soups', keyword: 'egusi', sort: 'popular' });
+  });
+
+  it('parses nested and flat pagination meta', () => {
+    const query = normalizeShopQuery({ page: 2 });
+    const nested = parseShopResponse({ data: [], meta: { pagination: { current_page: 2, last_page: 5, per_page: 24, total: 110, from: 25, to: 48, has_more: true } } } as never, query);
+    expect(nested.pagination).toEqual({ currentPage: 2, lastPage: 5, perPage: 24, total: 110, from: 25, to: 48, hasMore: true });
+    const flat = parseShopResponse({ data: [], meta: { current_page: 1, last_page: 1, total: 3 } } as never, normalizeShopQuery());
+    expect(flat.pagination).toMatchObject({ currentPage: 1, lastPage: 1, total: 3, hasMore: false, perPage: 24 });
+    expect(parseShopResponse({ data: [] } as never, query).pagination.currentPage).toBe(2);
+  });
+});

package/tests/use-shop-prefetch.test.tsx

@@ -0,0 +1,86 @@
+import { renderToStaticMarkup } from 'react-dom/server';
+import { describe, expect, it } from 'vitest';
+import type { JSX, ReactNode } from 'react';
+import { StorefrontContext } from '../provider';
+import { ShopPrefetchProvider, useShop } from '../hooks/use-shop';
+import { normalizeShopQuery, type ShopPrefetch } from '../utils/shop-query';
+import type { Product } from '../types/product';
+
+/**
+ * The server renders `/shop` with the first page already fetched. What matters
+ * is what that server render contains: with a matching prefetch the grid is in
+ * the HTML and nothing is loading; with anything else, useShop behaves exactly
+ * as before (empty + loading, then fetches in the browser).
+ */
+
+function product(id: string, title: string): Product {
+  return { id, title, slug: id } as unknown as Product;
+}
+
+const PREFETCH: ShopPrefetch = {
+  query: normalizeShopQuery({ categorySlug: 'soups', keyword: 'egusi', sort: 'popular', page: 1, perPage: 24 }),
+  products: [product('p1', 'Egusi Soup'), product('p2', 'Ogbono Soup')],
+  pagination: { currentPage: 1, lastPage: 1, perPage: 24, total: 2, from: 1, to: 2, hasMore: false },
+};
+
+function Grid(props: Parameters<typeof useShop>[0]): JSX.Element {
+  const { products, isLoading, pagination } = useShop(props);
+  return (
+    <ul data-loading={String(isLoading)} data-total={pagination.total}>
+      {products.map((p) => <li key={p.id}>{p.title}</li>)}
+    </ul>
+  );
+}
+
+function render(children: ReactNode, opts: { prefetch?: ShopPrefetch | null; preview?: Product[] } = {}): string {
+  const store = {
+    vendor: { id: 'v1', slug: 'kili-foods', name: 'Kili Foods' },
+    config: {},
+    menus: [],
+    previewData: opts.preview ? { products: opts.preview } : undefined,
+    basePath: '',
+    pagesChrome: {},
+  };
+  return renderToStaticMarkup(
+    <StorefrontContext.Provider value={store as never}>
+      <ShopPrefetchProvider value={opts.prefetch ?? null}>{children}</ShopPrefetchProvider>
+    </StorefrontContext.Provider>,
+  );
+}
+
+describe('useShop + ShopPrefetchProvider', () => {
+  it('renders the prefetched page when the query matches exactly', () => {
+    const html = render(<Grid categorySlug="soups" keyword="  egusi " sort="popular" page={1} perPage={24} />, { prefetch: PREFETCH });
+    expect(html).toContain('data-loading="false"');
+    expect(html).toContain('data-total="2"');
+    expect(html).toContain('Egusi Soup');
+    expect(html).toContain('Ogbono Soup');
+  });
+
+  it('ignores the prefetch for any other query (e.g. a product page\'s "popular" rail)', () => {
+    for (const other of [
+      { sort: 'popular' as const, perPage: 8, page: 1 },
+      { categorySlug: 'soups', keyword: 'egusi', sort: 'latest' as const },
+      { categorySlug: 'soups', keyword: 'egusi', sort: 'popular' as const, page: 2 },
+    ]) {
+      const html = render(<Grid {...other} />, { prefetch: PREFETCH });
+      expect(html).toContain('data-loading="true"');
+      expect(html).not.toContain('Egusi Soup');
+    }
+  });
+
+  it('behaves exactly as before with no provider value', () => {
+    const html = render(<Grid categorySlug="soups" keyword="egusi" sort="popular" />);
+    expect(html).toContain('data-loading="true"');
+    expect(html).toContain('data-total="0"');
+  });
+
+  it('preview mode keeps using the demo catalogue, never the prefetch', () => {
+    const html = render(<Grid categorySlug="soups" keyword="egusi" sort="popular" />, {
+      prefetch: PREFETCH,
+      preview: [{ ...product('d1', 'Demo Egusi'), categories: [{ slug: 'soups' }], excerpt: '', pricing: { sale_amount: 1 }, review_summary: { review_count: 0 } } as unknown as Product],
+    });
+    expect(html).toContain('Demo Egusi');
+    expect(html).not.toContain('Ogbono Soup');
+  });
+});

package/utils/format.ts

@@ -15,6 +15,33 @@
  * shows decimals only when the amount genuinely has them — ₦5,000 stays
  * ₦5,000, ₦0.28 now correctly shows as ₦0.28.
  */
+/**
+ * The locale and zone every date/number the kit DISPLAYS is formatted in.
+ * Fixed on purpose: storefront pages render on the server first, and a runtime
+ * default prints differently there (Node in UTC, en-US) than in the shopper's
+ * browser (Africa/Lagos, en-NG/en-GB) — "Feb 14, 2026" vs "14 Feb 2026". React
+ * then fails hydration and re-renders the whole page on the client. Queek's
+ * stores and shoppers are Nigerian, so that is the one answer both sides give.
+ */
+export const DISPLAY_LOCALE = 'en-NG';
+export const DISPLAY_TIME_ZONE = 'Africa/Lagos';
+
+/** A date for display (default "14 Feb 2026"), identical on server and browser. '' if unparseable. */
+export function formatDisplayDate(
+  value: string | number | Date,
+  options: Intl.DateTimeFormatOptions = { day: 'numeric', month: 'short', year: 'numeric' },
+  locale: string = DISPLAY_LOCALE,
+): string {
+  const date = value instanceof Date ? value : new Date(value);
+  if (Number.isNaN(date.getTime())) return '';
+  return date.toLocaleDateString(locale, { ...options, timeZone: DISPLAY_TIME_ZONE });
+}
+
+/** A count for display ("1,234"), identical on server and browser. */
+export function formatCount(value: number): string {
+  return value.toLocaleString(DISPLAY_LOCALE);
+}
+
 export function formatMoney(amount: number, currency = 'NGN'): string {
   try {
     return new Intl.NumberFormat('en-NG', {
@@ -24,7 +51,7 @@ export function formatMoney(amount: number, currency = 'NGN'): string {
       maximumFractionDigits: 2,
     }).format(amount);
   } catch {
-    return `${currency} ${amount.toLocaleString()}`;
+    return `${currency} ${amount.toLocaleString(DISPLAY_LOCALE)}`;
   }
 }
 

package/utils/shop-query.ts

@@ -0,0 +1,114 @@
+import type { ApiResponse, LegacyProductLike, Product } from '../types/product';
+import { extractProducts, normalizeProduct } from './product-normalizer';
+
+/**
+ * The shop catalogue query, in one place for both sides that run it: `useShop`
+ * in the browser and `fetchShopPrefetch` on the server. The server only saves
+ * the browser a fetch when the two would ask for exactly the same thing, so
+ * the parsing, the request params and the response handling cannot be allowed
+ * to drift — they live here, pure, with no React and no server imports.
+ */
+
+export type ShopSort = 'latest' | 'popular' | 'price_low' | 'price_high';
+
+export const SHOP_SORTS: readonly ShopSort[] = ['latest', 'popular', 'price_low', 'price_high'];
+
+/** What every theme's shop page asks for, and `useShop`'s default. */
+export const SHOP_DEFAULT_PER_PAGE = 24;
+
+export interface ShopPagination {
+  currentPage: number;
+  lastPage: number;
+  perPage: number;
+  total: number;
+  from: number | null;
+  to: number | null;
+  hasMore: boolean;
+}
+
+/** A shop query with every default applied — two equal queries fetch the same page. */
+export interface ShopQuery {
+  categorySlug: string | null;
+  keyword: string | null;
+  sort: ShopSort;
+  page: number;
+  perPage: number;
+}
+
+/** The first page the server already fetched, handed to `useShop` via `ShopPrefetchProvider`. */
+export interface ShopPrefetch {
+  query: ShopQuery;
+  products: Product[];
+  pagination: ShopPagination;
+}
+
+export function normalizeShopQuery(input?: {
+  categorySlug?: string | null;
+  keyword?: string | null;
+  sort?: ShopSort | null;
+  page?: number | null;
+  perPage?: number | null;
+}): ShopQuery {
+  const keyword = input?.keyword?.trim() ?? '';
+  const page = input?.page && input.page > 0 ? Math.floor(input.page) : 1;
+  return {
+    categorySlug: input?.categorySlug || null,
+    keyword: keyword === '' ? null : keyword,
+    sort: input?.sort && SHOP_SORTS.includes(input.sort) ? input.sort : 'latest',
+    page,
+    perPage: input?.perPage && input.perPage > 0 ? input.perPage : SHOP_DEFAULT_PER_PAGE,
+  };
+}
+
+export function sameShopQuery(a: ShopQuery, b: ShopQuery): boolean {
+  return a.categorySlug === b.categorySlug && a.keyword === b.keyword && a.sort === b.sort && a.page === b.page && a.perPage === b.perPage;
+}
+
+/**
+ * The `/shop` URL's filters — `category`, `q`, `sort`, `page` — exactly as
+ * `useShopParams` reads them. `get` is `URLSearchParams.get` or equivalent.
+ */
+export function parseShopSearchParams(get: (key: string) => string | null): {
+  categorySlug: string | null;
+  keyword: string;
+  sort: ShopSort;
+  page: number;
+} {
+  const sortRaw = get('sort');
+  const pageRaw = Number(get('page'));
+  return {
+    categorySlug: get('category'),
+    keyword: get('q') ?? '',
+    sort: SHOP_SORTS.includes(sortRaw as ShopSort) ? (sortRaw as ShopSort) : 'latest',
+    page: Number.isFinite(pageRaw) && pageRaw > 1 ? Math.floor(pageRaw) : 1,
+  };
+}
+
+/** Query params for `GET /products` (the storefront `/client/store` scope). */
+export function shopRequestParams(query: ShopQuery): Record<string, string | number> {
+  const params: Record<string, string | number> = { per_page: query.perPage, page: query.page };
+  if (query.categorySlug) params.category_slug = query.categorySlug;
+  if (query.keyword) params.keyword = query.keyword;
+  params.sort = query.sort;
+  return params;
+}
+
+export function parseShopResponse(
+  response: ApiResponse<unknown, Record<string, unknown>>,
+  query: ShopQuery,
+): { products: Product[]; pagination: ShopPagination } {
+  const meta = (response.meta ?? {}) as Record<string, unknown>;
+  const nestedMeta = (meta.pagination ?? meta) as Record<string, unknown>;
+  return {
+    pagination: {
+      currentPage: (nestedMeta.current_page as number) ?? query.page,
+      lastPage: (nestedMeta.last_page as number) ?? 1,
+      perPage: (nestedMeta.per_page as number) ?? query.perPage,
+      total: (nestedMeta.total as number) ?? 0,
+      from: (nestedMeta.from as number | null) ?? null,
+      to: (nestedMeta.to as number | null) ?? null,
+      hasMore: (nestedMeta.has_more as boolean) ?? false,
+    },
+    products: extractProducts(response.data).map((item) => normalizeProduct(item as LegacyProductLike)),
+  };
+}