@vitrine-kit/vitrine 0.4.1 → 0.5.0

package/kit/templates/backend-payload/files/lib/seed/demo.ts

@@ -1,10 +1,12 @@
-// Demo data for zero-config dev (§18.2): 5 products + 2 categories + local
-// placeholder images (seed-assets/). Prices are in minor units (e.g. cents):
-// 199000 = 1990.00. Pure data — covered by an invariants test.
+// Demo data for zero-config dev (§18.2): a small but realistic catalog so a
+// freshly scaffolded shop has browseable examples (categories, variants,
+// gallery images, SEO). Prices are integer minor units (cents): 2490 = $24.90.
+// Pure data — covered by invariants tests in sandbox.
 
 export interface DemoCategory {
   slug: string;
   title: string;
+  description: string;
 }
 
 export interface DemoVariant {
@@ -12,6 +14,8 @@ export interface DemoVariant {
   /** Minor units (e.g. cents). */
   price: number;
   stock: number;
+  /** e.g. { size: 'M', color: 'Black' }. */
+  options?: Record<string, string>;
 }
 
 export interface DemoProduct {
@@ -19,15 +23,23 @@ export interface DemoProduct {
   title: string;
   category: string;
   description: string;
-  /** File name in seed-assets/. */
-  image: string;
+  /** File names in seed-assets/ (first = cover; extras feed the gallery). */
+  images: string[];
   seo: { title: string; description: string };
   variants: DemoVariant[];
 }
 
 export const demoCategories: DemoCategory[] = [
-  { slug: 'apparel', title: 'Apparel' },
-  { slug: 'accessories', title: 'Accessories' },
+  {
+    slug: 'apparel',
+    title: 'Apparel',
+    description: 'Everyday layers — tees, hoodies, and socks with size options you can add to the cart.',
+  },
+  {
+    slug: 'accessories',
+    title: 'Accessories',
+    description: 'Caps and bags that round out a simple merch assortment.',
+  },
 ];
 
 export const demoProducts: DemoProduct[] = [
@@ -35,45 +47,79 @@ export const demoProducts: DemoProduct[] = [
     slug: 'classic-tee',
     title: 'Classic T-Shirt',
     category: 'apparel',
-    description: 'A straight-cut cotton T-shirt.',
-    image: 'placeholder-1.svg',
-    seo: { title: 'Classic T-Shirt', description: 'A basic cotton T-shirt.' },
-    variants: [{ sku: 'TEE-001', price: 199000, stock: 25 }],
+    description:
+      'A straight-cut midweight cotton tee for daily wear. Soft hand-feel, reinforced shoulder seams, and a slightly longer hem that stays tucked. Pick a size below, add it to your cart, then open /cart to try checkout.',
+    images: ['placeholder-1.svg', 'placeholder-1b.svg'],
+    seo: {
+      title: 'Classic T-Shirt — midweight cotton',
+      description: 'Demo apparel product with multiple sizes. Midweight cotton, straight cut.',
+    },
+    variants: [
+      { sku: 'TEE-S', price: 2490, stock: 18, options: { size: 'S' } },
+      { sku: 'TEE-M', price: 2490, stock: 32, options: { size: 'M' } },
+      { sku: 'TEE-L', price: 2490, stock: 21, options: { size: 'L' } },
+      { sku: 'TEE-XL', price: 2690, stock: 9, options: { size: 'XL' } },
+    ],
   },
   {
     slug: 'zip-hoodie',
     title: 'Zip Hoodie',
     category: 'apparel',
-    description: 'A warm hooded sweatshirt.',
-    image: 'placeholder-2.svg',
-    seo: { title: 'Zip Hoodie', description: 'An insulated hoodie.' },
-    variants: [{ sku: 'HOD-001', price: 459000, stock: 12 }],
+    description:
+      'A brushed-fleece zip hoodie with a roomy hood and metal zipper. Wear it open over the Classic Tee or zipped for cooler evenings. Sizes share the same cut; XL is a touch longer in the body.',
+    images: ['placeholder-2.svg', 'placeholder-2b.svg'],
+    seo: {
+      title: 'Zip Hoodie — brushed fleece',
+      description: 'Demo hoodie with size variants and a two-image gallery.',
+    },
+    variants: [
+      { sku: 'HOD-S', price: 6900, stock: 8, options: { size: 'S' } },
+      { sku: 'HOD-M', price: 6900, stock: 14, options: { size: 'M' } },
+      { sku: 'HOD-L', price: 6900, stock: 11, options: { size: 'L' } },
+      { sku: 'HOD-XL', price: 7200, stock: 4, options: { size: 'XL' } },
+    ],
   },
   {
     slug: 'logo-cap',
     title: 'Logo Cap',
     category: 'accessories',
-    description: 'An adjustable cap.',
-    image: 'placeholder-3.svg',
-    seo: { title: 'Cap', description: 'A cap with a logo.' },
-    variants: [{ sku: 'CAP-001', price: 129000, stock: 40 }],
+    description:
+      'A structured six-panel cap with an adjustable strap. One size fits most; choose color to see how option-based variants appear on accessories.',
+    images: ['placeholder-3.svg'],
+    seo: {
+      title: 'Logo Cap — adjustable',
+      description: 'Demo accessory with color options.',
+    },
+    variants: [
+      { sku: 'CAP-BLK', price: 2900, stock: 24, options: { color: 'Black' } },
+      { sku: 'CAP-NAV', price: 2900, stock: 16, options: { color: 'Navy' } },
+      { sku: 'CAP-SND', price: 2900, stock: 12, options: { color: 'Sand' } },
+    ],
   },
   {
     slug: 'tote-bag',
     title: 'Tote Bag',
     category: 'accessories',
-    description: 'A sturdy cotton tote.',
-    image: 'placeholder-4.svg',
-    seo: { title: 'Tote', description: 'A cotton tote bag.' },
-    variants: [{ sku: 'TOT-001', price: 99000, stock: 60 }],
+    description:
+      'A heavyweight canvas tote with an interior pocket. Single SKU — useful for comparing a simple product against multi-variant apparel on the product page.',
+    images: ['placeholder-4.svg'],
+    seo: {
+      title: 'Tote Bag — heavyweight canvas',
+      description: 'Demo single-variant accessory for a simple add-to-cart path.',
+    },
+    variants: [{ sku: 'TOT-001', price: 1800, stock: 60 }],
   },
   {
     slug: 'crew-socks',
-    title: 'Socks, 3 Pairs',
+    title: 'Crew Socks (3-Pack)',
     category: 'apparel',
-    description: 'A set of three pairs.',
-    image: 'placeholder-5.svg',
-    seo: { title: 'Socks', description: 'A pack of socks, 3 pairs.' },
-    variants: [{ sku: 'SOC-001', price: 79000, stock: 100 }],
+    description:
+      'A three-pair pack of ribbed crew socks. Soft cuff, reinforced heel and toe. Sold as one pack SKU so cart lines stay simple while you explore quantity updates on /cart.',
+    images: ['placeholder-5.svg'],
+    seo: {
+      title: 'Crew Socks — 3-pack',
+      description: 'Demo pack product with a single variant and high stock.',
+    },
+    variants: [{ sku: 'SOC-3PK', price: 1400, stock: 100 }],
   },
 ];

package/kit/templates/backend-payload/files/lib/seed/guards.ts

@@ -1,5 +1,18 @@
-// Pure guards for zero-config dev procedures (§18). The seed and dev admin run
-// ONLY in dev AND when the collection is empty — idempotent and never in prod.
-export function shouldRunDevTask(opts: { isProd: boolean; existingCount: number }): boolean {
-  return !opts.isProd && opts.existingCount === 0;
+// Pure guards for zero-config bootstrap (§18). Seed and dev admin run when the
+// collection is empty — in development always, and in production only when
+// SEED_ON_BOOT=1 (docker compose demos / first boot).
+export function shouldRunDevTask(opts: {
+  isProd: boolean;
+  existingCount: number;
+  /** When true, allow empty-collection bootstrap even in production. */
+  seedOnBoot?: boolean;
+}): boolean {
+  if (opts.existingCount !== 0) return false;
+  if (!opts.isProd) return true;
+  return Boolean(opts.seedOnBoot);
+}
+
+export function seedOnBootEnabled(): boolean {
+  const v = process.env.SEED_ON_BOOT?.trim().toLowerCase();
+  return v === '1' || v === 'true' || v === 'yes';
 }

package/kit/templates/backend-payload/files/lib/seed/locales.ts

@@ -0,0 +1,53 @@
+// Optional non-default locale copy for the demo seed when Payload localization is enabled.
+// Slugs stay shared; only human-readable fields differ.
+
+export const demoLocales = {
+  categories: {
+    apparel: {
+      ru: {
+        title: 'Одежда',
+        description: 'Повседневные слои — футболки, худи и носки с выбором размера.',
+      },
+    },
+    accessories: {
+      ru: {
+        title: 'Аксессуары',
+        description: 'Кепки и сумки, которые дополняют простой мерч-ассортимент.',
+      },
+    },
+  },
+  products: {
+    'classic-tee': {
+      ru: {
+        title: 'Классическая футболка',
+        description:
+          'Прямой крой из хлопка средней плотности на каждый день. Мягкая фактура, усиленные плечевые швы. Выберите размер ниже и добавьте в корзину.',
+        seo: {
+          title: 'Классическая футболка — хлопок',
+          description: 'Демо-товар одежды с несколькими размерами.',
+        },
+      },
+    },
+    'zip-hoodie': {
+      ru: {
+        title: 'Худи на молнии',
+        description:
+          'Флисовое худи на молнии с объёмным капюшоном. Носите поверх футболки или застёгнутым в прохладный вечер.',
+        seo: {
+          title: 'Худи на молнии — флис',
+          description: 'Демо-худи с размерами и галереей.',
+        },
+      },
+    },
+    'logo-cap': {
+      ru: {
+        title: 'Кепка с логотипом',
+        description: 'Структурированная кепка с регулируемой застёжкой. Выберите цвет и добавьте в корзину.',
+        seo: {
+          title: 'Кепка с логотипом',
+          description: 'Демо-аксессуар с цветовыми вариантами.',
+        },
+      },
+    },
+  },
+} as const;

package/kit/templates/backend-payload/files/lib/seed/run.ts

@@ -1,32 +1,75 @@
-// Demo seed (§18.2): runs from Payload's onInit. Idempotent (guarded by
-// shouldRunDevTask: dev only + empty collection). Images are local
-// placeholders from seed-assets/ (no network).
+// Demo seed (§18.2): runs from Payload's onInit. Idempotent (empty collection +
+// dev, or SEED_ON_BOOT=1 in production). Images are local placeholders from
+// seed-assets/ (no network). Optional RU copy is applied when localization is on.
+import { existsSync } from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import type { Payload } from 'payload';
 import { demoCategories, demoProducts } from './demo.js';
-import { shouldRunDevTask } from './guards.js';
+import { seedOnBootEnabled, shouldRunDevTask } from './guards.js';
+import { demoLocales } from './locales.js';
 import { plainToRichText } from './richtext.js';
 
-const seedAssets = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../seed-assets');
+// Prefer cwd/seed-assets so Docker runtime (standalone) can ship the folder next to server.js.
+const seedAssets = [
+  path.resolve(process.cwd(), 'seed-assets'),
+  path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../seed-assets'),
+].find((p) => existsSync(p));
 
 export async function seedDemo(payload: Payload): Promise<void> {
   const isProd = process.env.NODE_ENV === 'production';
   const { totalDocs } = await payload.count({ collection: 'products' });
-  if (!shouldRunDevTask({ isProd, existingCount: totalDocs })) return;
+  if (!shouldRunDevTask({ isProd, existingCount: totalDocs, seedOnBoot: seedOnBootEnabled() })) {
+    return;
+  }
+  if (!seedAssets) {
+    payload.logger.warn('[vitrine] demo seed skipped — seed-assets/ not found');
+    return;
+  }
+
+  const localization = payload.config.localization;
+  const defaultLocale = localization?.defaultLocale ?? 'en';
+  const enabledLocales = new Set(
+    (localization?.locales ?? []).map((l) => (typeof l === 'string' ? l : l.code)),
+  );
+  const createOpts = localization ? { locale: defaultLocale as 'en' } : {};
 
   const categoryId = new Map<string, string | number>();
   for (const c of demoCategories) {
-    const doc = await payload.create({ collection: 'categories', data: { slug: c.slug, title: c.title } });
+    const doc = await payload.create({
+      collection: 'categories',
+      data: { slug: c.slug, title: c.title, description: c.description },
+      ...createOpts,
+      overrideAccess: true,
+    });
     categoryId.set(c.slug, doc.id);
+    const localized = demoLocales.categories[c.slug];
+    if (localized && localization) {
+      for (const [locale, copy] of Object.entries(localized)) {
+        if (locale === defaultLocale || !enabledLocales.has(locale)) continue;
+        await payload.update({
+          collection: 'categories',
+          id: doc.id,
+          data: { title: copy.title, description: copy.description },
+          locale: locale as 'en',
+          overrideAccess: true,
+        });
+      }
+    }
   }
 
   for (const p of demoProducts) {
-    const media = await payload.create({
-      collection: 'media',
-      data: { alt: p.title },
-      filePath: path.join(seedAssets, p.image),
-    });
+    const mediaIds: Array<string | number> = [];
+    for (const [index, image] of p.images.entries()) {
+      const media = await payload.create({
+        collection: 'media',
+        data: { alt: index === 0 ? p.title : `${p.title} — detail` },
+        filePath: path.join(seedAssets, image),
+        overrideAccess: true,
+      });
+      mediaIds.push(media.id);
+    }
+    const coverId = mediaIds[0];
     const catId = categoryId.get(p.category);
     const product = await payload.create({
       collection: 'products',
@@ -35,17 +78,50 @@ export async function seedDemo(payload: Payload): Promise<void> {
         title: p.title,
         description: plainToRichText(p.description),
         categories: catId ? [catId] : [],
-        images: [media.id],
-        seo: { title: p.seo.title, description: p.seo.description, image: media.id },
+        images: mediaIds,
+        seo: {
+          title: p.seo.title,
+          description: p.seo.description,
+          image: coverId,
+        },
       },
+      ...createOpts,
+      overrideAccess: true,
     });
+    const localized = demoLocales.products[p.slug];
+    if (localized && localization) {
+      for (const [locale, copy] of Object.entries(localized)) {
+        if (locale === defaultLocale || !enabledLocales.has(locale)) continue;
+        await payload.update({
+          collection: 'products',
+          id: product.id,
+          data: {
+            title: copy.title,
+            description: plainToRichText(copy.description),
+            seo: { title: copy.seo.title, description: copy.seo.description },
+          },
+          locale: locale as 'en',
+          overrideAccess: true,
+        });
+      }
+    }
     for (const v of p.variants) {
       await payload.create({
         collection: 'variants',
-        data: { sku: v.sku, price: v.price, stock: v.stock, product: product.id },
+        data: {
+          sku: v.sku,
+          price: v.price,
+          stock: v.stock,
+          product: product.id,
+          ...(v.options ? { options: v.options } : {}),
+        },
+        overrideAccess: true,
       });
     }
   }
 
-  payload.logger.info('[vitrine] demo seed: created 5 products');
+  const variantCount = demoProducts.reduce((n, p) => n + p.variants.length, 0);
+  payload.logger.info(
+    `[vitrine] demo seed: ${demoProducts.length} products, ${demoCategories.length} categories, ${variantCount} variants — browse / then try Add to cart`,
+  );
 }

package/kit/templates/backend-payload/files/next.config.mjs

@@ -2,9 +2,43 @@
 // API into Next). output: 'standalone' — for the Docker image (VPS).
 import { withPayload } from '@payloadcms/next/withPayload';
 
+// Baseline security headers (OWASP A05: Security Misconfiguration) applied to every route.
+// The CSP below is a conservative starting point — payment providers with client-side widgets
+// (e.g. embedded Stripe Elements) may need their domains added to script-src/connect-src/frame-src.
+// Next.js `pnpm dev` (webpack eval source maps / Fast Refresh) needs 'unsafe-eval'; omit it in
+// production builds so the shipped CSP stays tighter.
+const isDev = process.env.NODE_ENV !== 'production';
+const scriptSrc = isDev
+  ? "script-src 'self' 'unsafe-inline' 'unsafe-eval'"
+  : "script-src 'self' 'unsafe-inline'";
+
+const securityHeaders = [
+  { key: 'X-Content-Type-Options', value: 'nosniff' },
+  { key: 'X-Frame-Options', value: 'DENY' },
+  { key: 'Referrer-Policy', value: 'strict-origin-when-cross-origin' },
+  { key: 'Permissions-Policy', value: 'camera=(), microphone=(), geolocation=()' },
+  { key: 'Strict-Transport-Security', value: 'max-age=63072000; includeSubDomains; preload' },
+  {
+    key: 'Content-Security-Policy',
+    value: `default-src 'self'; ${scriptSrc}; style-src 'self' 'unsafe-inline'; img-src 'self' data: https:; font-src 'self' data:; connect-src 'self' https:; frame-ancestors 'none';`,
+  },
+];
+
 /** @type {import('next').NextConfig} */
 const nextConfig = {
   output: 'standalone',
+  // Registry/template sources use TypeScript ESM-style relative imports (`.js` → `.ts`/`.tsx`).
+  // Webpack needs an explicit extensionAlias; without it, `pnpm dev` fails to resolve components.
+  webpack(config) {
+    config.resolve.extensionAlias = {
+      ...(config.resolve.extensionAlias ?? {}),
+      '.js': ['.ts', '.tsx', '.js', '.jsx'],
+    };
+    return config;
+  },
+  async headers() {
+    return [{ source: '/:path*', headers: securityHeaders }];
+  },
 };
 
 export default withPayload(nextConfig);

package/kit/templates/backend-payload/files/payload.config.ts

@@ -1,19 +1,47 @@
 // The client's Payload 3 config. Collections are assembled by the blueprint (base +
 // additive feature extensions, lib/blueprint.ts — generated by the CLI). The DB is
-// chosen zero-config (db.ts → §18.1). onInit runs the demo seed and dev admin (dev only).
+// chosen zero-config (db.ts → §18.1). onInit runs the demo seed and boot admin.
+// Email adapter is optional — present when the `email` feature is installed.
+// Localization mirrors site.config i18n when more than one locale is configured.
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { buildConfig } from 'payload';
 import type { CollectionConfig } from 'payload';
+import { buildConfig } from 'payload';
 import { lexicalEditor } from '@payloadcms/richtext-lexical';
 import sharp from 'sharp';
 import { collections } from './lib/blueprint.js';
 import { resolveDbAdapter } from './lib/adapter/db.js';
 import { seedDemo } from './lib/seed/run.js';
 import { ensureDevAdmin } from './lib/seed/admin.js';
+import { siteConfig } from './site.config.js';
 
 const dirname = path.dirname(fileURLToPath(import.meta.url));
 
+// Empty string from `cp .env.example .env` must not count as set (?? only skips null/undefined).
+const payloadSecret = process.env.PAYLOAD_SECRET?.trim() || undefined;
+if (!payloadSecret && process.env.NODE_ENV === 'production') {
+  // No silent fallback to the dev secret in production (mirrors the Vendure DATABASE_URL guard).
+  throw new Error('[vitrine] PAYLOAD_SECRET is required in production');
+}
+
+async function loadEmailAdapter(): Promise<unknown> {
+  try {
+    const mod = await import('./lib/email/adapter.js');
+    return await mod.resolveEmailAdapter();
+  } catch {
+    return undefined;
+  }
+}
+
+const email = await loadEmailAdapter();
+
+const locales = siteConfig.i18n.locales.filter(Boolean);
+const localization = {
+  locales: locales.length > 0 ? locales : ['en'],
+  defaultLocale: siteConfig.i18n.defaultLocale || locales[0] || 'en',
+  fallback: true,
+};
+
 export default buildConfig({
   admin: {
     user: 'users',
@@ -21,9 +49,11 @@ export default buildConfig({
   },
   collections: collections as unknown as CollectionConfig[],
   editor: lexicalEditor(),
-  secret: process.env.PAYLOAD_SECRET ?? 'dev-secret-change-me',
+  secret: payloadSecret ?? 'dev-secret-change-me',
   db: await resolveDbAdapter(),
   sharp,
+  localization,
+  ...(email ? { email: email as never } : {}),
   typescript: { outputFile: path.resolve(dirname, 'payload-types.ts') },
   async onInit(payload) {
     await seedDemo(payload);

package/kit/templates/backend-payload/files/seed-assets/placeholder-1b.svg

@@ -0,0 +1,6 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="600" height="600" viewBox="0 0 600 600" role="img" aria-label="Classic T-Shirt detail">
+  <rect width="600" height="600" fill="#f5f5f4"/>
+  <rect x="40" y="40" width="520" height="520" rx="16" fill="#e7e5e4"/>
+  <text x="300" y="290" font-family="system-ui, sans-serif" font-size="36" fill="#57534e" text-anchor="middle">T-Shirt</text>
+  <text x="300" y="340" font-family="system-ui, sans-serif" font-size="22" fill="#78716c" text-anchor="middle">detail view</text>
+</svg>

package/kit/templates/backend-payload/files/seed-assets/placeholder-2b.svg

@@ -0,0 +1,6 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="600" height="600" viewBox="0 0 600 600" role="img" aria-label="Zip Hoodie detail">
+  <rect width="600" height="600" fill="#fafaf9"/>
+  <rect x="40" y="40" width="520" height="520" rx="16" fill="#e7e5e4"/>
+  <text x="300" y="290" font-family="system-ui, sans-serif" font-size="36" fill="#44403c" text-anchor="middle">Hoodie</text>
+  <text x="300" y="340" font-family="system-ui, sans-serif" font-size="22" fill="#78716c" text-anchor="middle">detail view</text>
+</svg>

package/kit/templates/backend-vendure/files/Dockerfile

@@ -1,6 +1,6 @@
 # syntax=docker/dockerfile:1
 # Vitrine client image on Vendure. One image, two commands (compose): the Vendure server
-# (`node dist/index.js`) and the Next storefront (`next start`). Target — VPS.
+# (`pnpm exec tsx src/index.ts`) and the Next storefront (`pnpm start`). Target — VPS.
 FROM node:20-alpine AS base
 RUN corepack enable && corepack prepare pnpm@9.15.0 --activate
 WORKDIR /app

package/kit/templates/backend-vendure/files/docker-compose.yml

@@ -20,7 +20,8 @@ services:
     build:
       context: .
     restart: unless-stopped
-    command: ['node', 'dist/index.js']
+    # tsx is available from the full build image; avoids a separate server compile step.
+    command: ['pnpm', 'exec', 'tsx', 'src/index.ts']
     environment:
       NODE_ENV: production
       DATABASE_URL: postgres://vitrine:${POSTGRES_PASSWORD:-vitrine}@db:5432/vitrine

package/kit/templates/backend-vendure/files/lib/adapter/product-query.ts

@@ -0,0 +1,126 @@
+// Pure ProductQuery helpers — filter/sort in memory after the adapter loads products.
+// Price lives on variants, so Payload cannot ORDER BY price in SQL without a denormalized
+// field; this keeps the contract honest for catalog-sized datasets.
+import type { Product, ProductQuery, ProductSort } from '@vitrine-kit/contracts';
+
+export function parseProductSort(value: string | undefined | null): ProductSort | undefined {
+  if (value === 'newest' || value === 'price-asc' || value === 'price-desc' || value === 'relevance') {
+    return value;
+  }
+  return undefined;
+}
+
+/** Parse `?size=S&size=L&color=Black` style params into ProductQuery.filters. */
+export function parseProductFilters(
+  params: Record<string, string | string[] | undefined>,
+  facetKeys: string[] = ['size', 'color'],
+): Record<string, string[]> | undefined {
+  const filters: Record<string, string[]> = {};
+  for (const key of facetKeys) {
+    const raw = params[key];
+    if (raw == null) continue;
+    const values = (Array.isArray(raw) ? raw : [raw])
+      .flatMap((v) => String(v).split(','))
+      .map((v) => v.trim())
+      .filter(Boolean);
+    if (values.length) filters[key] = [...new Set(values)];
+  }
+  return Object.keys(filters).length ? filters : undefined;
+}
+
+export function parsePriceBound(
+  value: string | string[] | undefined | null,
+): number | undefined {
+  const raw = Array.isArray(value) ? value[0] : value;
+  if (raw == null || raw === '') return undefined;
+  const n = Number(raw);
+  if (!Number.isFinite(n) || n < 0) return undefined;
+  // URL values are major currency units ($); ProductQuery uses minor units.
+  return Math.round(n * 100);
+}
+
+/** Aggregate option values present on the given products (for toolbar facets). */
+export function collectOptionFacets(products: Product[]): Record<string, string[]> {
+  const buckets = new Map<string, Set<string>>();
+  for (const p of products) {
+    for (const v of p.variants) {
+      if (!v.options) continue;
+      for (const [key, val] of Object.entries(v.options)) {
+        if (!val) continue;
+        let set = buckets.get(key);
+        if (!set) {
+          set = new Set();
+          buckets.set(key, set);
+        }
+        set.add(val);
+      }
+    }
+  }
+  const out: Record<string, string[]> = {};
+  for (const [key, set] of [...buckets.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+    out[key] = [...set].sort((a, b) => a.localeCompare(b));
+  }
+  return out;
+}
+
+function matchesFilters(product: Product, filters: Record<string, string[]>): boolean {
+  for (const [key, wanted] of Object.entries(filters)) {
+    if (!wanted.length) continue;
+    const has = product.variants.some((v) => {
+      const actual = v.options?.[key];
+      return actual != null && wanted.includes(actual);
+    });
+    if (!has) return false;
+  }
+  return true;
+}
+
+function matchesSearch(product: Product, term: string): boolean {
+  const q = term.trim().toLowerCase();
+  if (!q) return true;
+  const hay = `${product.title} ${product.description ?? ''} ${product.slug}`.toLowerCase();
+  return hay.includes(q);
+}
+
+function priceOf(product: Product): number {
+  return product.priceRange?.min ?? product.variants[0]?.price ?? Number.POSITIVE_INFINITY;
+}
+
+function matchesPrice(product: Product, priceMin?: number, priceMax?: number): boolean {
+  if (priceMin == null && priceMax == null) return true;
+  // A product matches if any variant price falls in range (merchandising expectation).
+  return product.variants.some((v) => {
+    if (priceMin != null && v.price < priceMin) return false;
+    if (priceMax != null && v.price > priceMax) return false;
+    return true;
+  });
+}
+
+/** Apply search / filters / sort that the DB layer cannot express cheaply. */
+export function applyProductQuery(products: Product[], query: ProductQuery = {}): Product[] {
+  let out = products;
+  if (query.search?.trim()) {
+    out = out.filter((p) => matchesSearch(p, query.search!));
+  }
+  if (query.filters && Object.keys(query.filters).length > 0) {
+    out = out.filter((p) => matchesFilters(p, query.filters!));
+  }
+  if (query.priceMin != null || query.priceMax != null) {
+    out = out.filter((p) => matchesPrice(p, query.priceMin, query.priceMax));
+  }
+  const sort = query.sort ?? 'newest';
+  if (sort === 'price-asc') {
+    out = [...out].sort((a, b) => priceOf(a) - priceOf(b));
+  } else if (sort === 'price-desc') {
+    out = [...out].sort((a, b) => priceOf(b) - priceOf(a));
+  } else if (sort === 'relevance' && query.search?.trim()) {
+    const q = query.search.trim().toLowerCase();
+    out = [...out].sort((a, b) => {
+      const aTitle = a.title.toLowerCase().startsWith(q) ? 0 : a.title.toLowerCase().includes(q) ? 1 : 2;
+      const bTitle = b.title.toLowerCase().startsWith(q) ? 0 : b.title.toLowerCase().includes(q) ? 1 : 2;
+      return aTitle - bTitle || a.title.localeCompare(b.title);
+    });
+  }
+  // newest: keep adapter order (typically -createdAt)
+  return out;
+}